Initial commit

2025-11-30 08:24:34 +08:00
commit 4ad7b3dd73
15 changed files with 4798 additions and 0 deletions
--- a/references/wrangler-commands.md
+++ b/references/wrangler-commands.md
@@ -0,0 +1,378 @@
+# Wrangler Vectorize Commands Reference
+
+Complete CLI reference for managing Cloudflare Vectorize indexes with Wrangler.
+
+**Minimum Version Required**: Wrangler 3.71.0+
+
+## Index Management
+
+### create
+
+Create a new Vectorize index.
+
+**⚠️ CRITICAL**: Dimensions and metric cannot be changed after creation!
+
+```bash
+npx wrangler vectorize create <INDEX_NAME> \
+  --dimensions=<NUMBER> \
+  --metric=<METRIC> \
+  [--description=<TEXT>]
+```
+
+**Parameters**:
+- `INDEX_NAME` (required): Name of the index (lowercase, alphanumeric, dashes, max 32 chars)
+- `--dimensions` (required): Vector width (768 for Workers AI bge-base, 1536 for OpenAI small, 3072 for OpenAI large)
+- `--metric` (required): Distance metric (`cosine`, `euclidean`, or `dot-product`)
+- `--description` (optional): Human-readable description
+
+**Examples**:
+```bash
+# Workers AI @cf/baai/bge-base-en-v1.5 (768 dimensions)
+npx wrangler vectorize create docs-search \
+  --dimensions=768 \
+  --metric=cosine \
+  --description="Documentation semantic search"
+
+# OpenAI text-embedding-3-small (1536 dimensions)
+npx wrangler vectorize create product-recs \
+  --dimensions=1536 \
+  --metric=cosine
+
+# OpenAI text-embedding-3-large (3072 dimensions)
+npx wrangler vectorize create high-accuracy-index \
+  --dimensions=3072 \
+  --metric=euclidean
+```
+
+### list
+
+List all Vectorize indexes in your account.
+
+```bash
+npx wrangler vectorize list
+```
+
+**Output**: Table with index names, dimensions, and distance metrics.
+
+### get
+
+Get details about a specific index.
+
+```bash
+npx wrangler vectorize get <INDEX_NAME>
+```
+
+**Returns**: Index configuration (name, dimensions, metric, description).
+
+### info
+
+Get additional information about an index.
+
+```bash
+npx wrangler vectorize info <INDEX_NAME>
+```
+
+**Returns**: Vector count, last processed mutation, index status.
+
+### delete
+
+Delete a Vectorize index (irreversible!).
+
+```bash
+npx wrangler vectorize delete <INDEX_NAME> [--force]
+```
+
+**Parameters**:
+- `--force` (optional): Skip confirmation prompt
+
+**Example**:
+```bash
+npx wrangler vectorize delete old-index --force
+```
+
+## Metadata Indexes
+
+**⚠️ CRITICAL**: Create metadata indexes BEFORE inserting vectors! Vectors added before a metadata index exists won't be filterable on that property.
+
+### create-metadata-index
+
+Enable metadata filtering on a specific property.
+
+```bash
+npx wrangler vectorize create-metadata-index <INDEX_NAME> \
+  --property-name=<PROPERTY> \
+  --type=<TYPE>
+```
+
+**Parameters**:
+- `INDEX_NAME` (required): Vectorize index name
+- `--property-name` (required): Metadata field name
+- `--type` (required): Data type (`string`, `number`, or `boolean`)
+
+**Limits**:
+- Max 10 metadata indexes per Vectorize index
+- String indexes: First 64 bytes (UTF-8)
+- Number indexes: Float64 precision
+
+**Examples**:
+```bash
+# String metadata (category filtering)
+npx wrangler vectorize create-metadata-index docs-search \
+  --property-name=category \
+  --type=string
+
+# Number metadata (timestamp filtering)
+npx wrangler vectorize create-metadata-index docs-search \
+  --property-name=published_at \
+  --type=number
+
+# Boolean metadata (published status)
+npx wrangler vectorize create-metadata-index docs-search \
+  --property-name=published \
+  --type=boolean
+
+# Nested metadata (use dot notation)
+npx wrangler vectorize create-metadata-index docs-search \
+  --property-name=author_verified \
+  --type=boolean
+```
+
+### list-metadata-index
+
+List all metadata indexes for an index.
+
+```bash
+npx wrangler vectorize list-metadata-index <INDEX_NAME>
+```
+
+**Output**: Table with property names and types.
+
+### delete-metadata-index
+
+Disable metadata filtering on a property.
+
+```bash
+npx wrangler vectorize delete-metadata-index <INDEX_NAME> \
+  --property-name=<PROPERTY>
+```
+
+**Example**:
+```bash
+npx wrangler vectorize delete-metadata-index docs-search \
+  --property-name=category
+```
+
+## Vector Operations
+
+### insert
+
+Insert vectors from a file (NDJSON format).
+
+```bash
+npx wrangler vectorize insert <INDEX_NAME> \
+  --file=<PATH>
+```
+
+**File Format** (NDJSON - one JSON object per line):
+```json
+{"id":"1","values":[0.1,0.2,0.3],"metadata":{"title":"Doc 1"}}
+{"id":"2","values":[0.4,0.5,0.6],"metadata":{"title":"Doc 2"}}
+```
+
+**Example**:
+```bash
+npx wrangler vectorize insert docs-search --file=vectors.ndjson
+```
+
+### query
+
+Query vectors directly from CLI.
+
+```bash
+npx wrangler vectorize query <INDEX_NAME> \
+  --vector="[<COMMA_SEPARATED_FLOATS>]" \
+  [--top-k=<NUMBER>] \
+  [--return-metadata=<MODE>] \
+  [--namespace=<NAMESPACE>] \
+  [--filter=<JSON>]
+```
+
+**Parameters**:
+- `--vector` (required): Query vector as JSON array
+- `--top-k` (optional): Number of results (default: 10)
+- `--return-metadata` (optional): `none`, `indexed`, or `all` (default: `none`)
+- `--namespace` (optional): Query specific namespace
+- `--filter` (optional): Metadata filter as JSON string
+
+**Examples**:
+```bash
+# Simple query
+npx wrangler vectorize query docs-search \
+  --vector="[0.1,0.2,0.3,...]" \
+  --top-k=5 \
+  --return-metadata=all
+
+# Query with filter
+npx wrangler vectorize query docs-search \
+  --vector="[0.1,0.2,...]" \
+  --filter='{"category":"documentation","published":true}' \
+  --top-k=3
+
+# Query specific namespace
+npx wrangler vectorize query docs-search \
+  --vector="[0.1,0.2,...]" \
+  --namespace="customer-123" \
+  --top-k=5
+```
+
+### list-vectors
+
+List vector IDs in paginated manner.
+
+```bash
+npx wrangler vectorize list-vectors <INDEX_NAME> \
+  [--count=<NUMBER>] \
+  [--cursor=<CURSOR>]
+```
+
+**Parameters**:
+- `--count` (optional): Vectors per page (1-1000, default: 100)
+- `--cursor` (optional): Pagination cursor from previous response
+
+**Example**:
+```bash
+# Get first 100 vector IDs
+npx wrangler vectorize list-vectors docs-search --count=100
+
+# Get next page (use cursor from previous response)
+npx wrangler vectorize list-vectors docs-search \
+  --count=100 \
+  --cursor="abc123..."
+```
+
+### get-vectors
+
+Fetch specific vectors by ID.
+
+```bash
+npx wrangler vectorize get-vectors <INDEX_NAME> \
+  --ids=<ID1,ID2,ID3>
+```
+
+**Example**:
+```bash
+npx wrangler vectorize get-vectors docs-search \
+  --ids="doc-1,doc-2,doc-3"
+```
+
+### delete-vectors
+
+Delete vectors by ID.
+
+```bash
+npx wrangler vectorize delete-vectors <INDEX_NAME> \
+  --ids=<ID1,ID2,ID3>
+```
+
+**Example**:
+```bash
+npx wrangler vectorize delete-vectors docs-search \
+  --ids="old-doc-1,old-doc-2"
+```
+
+## Common Workflows
+
+### Initial Setup
+
+```bash
+# 1. Create index
+npx wrangler vectorize create my-index \
+  --dimensions=768 \
+  --metric=cosine
+
+# 2. Create metadata indexes (BEFORE inserting!)
+npx wrangler vectorize create-metadata-index my-index \
+  --property-name=category --type=string
+
+npx wrangler vectorize create-metadata-index my-index \
+  --property-name=timestamp --type=number
+
+# 3. Verify metadata indexes
+npx wrangler vectorize list-metadata-index my-index
+
+# 4. Now safe to insert vectors (via Worker or CLI)
+```
+
+### Bulk Data Import
+
+```bash
+# Prepare NDJSON file
+cat > vectors.ndjson << 'EOF'
+{"id":"doc-1","values":[0.1,0.2,0.3,...],"metadata":{"category":"docs"}}
+{"id":"doc-2","values":[0.4,0.5,0.6,...],"metadata":{"category":"tutorials"}}
+EOF
+
+# Import
+npx wrangler vectorize insert my-index --file=vectors.ndjson
+
+# Verify
+npx wrangler vectorize info my-index
+```
+
+### Debug / Inspect
+
+```bash
+# Check index configuration
+npx wrangler vectorize get my-index
+
+# Check vector count
+npx wrangler vectorize info my-index
+
+# List some vector IDs
+npx wrangler vectorize list-vectors my-index --count=10
+
+# Inspect specific vectors
+npx wrangler vectorize get-vectors my-index --ids="doc-1,doc-2"
+
+# Test query
+npx wrangler vectorize query my-index \
+  --vector="[0.1,0.2,...]" \
+  --top-k=3 \
+  --return-metadata=all
+```
+
+### Cleanup
+
+```bash
+# Delete specific vectors
+npx wrangler vectorize delete-vectors my-index --ids="doc-1,doc-2"
+
+# Delete entire index (irreversible!)
+npx wrangler vectorize delete my-index --force
+```
+
+## Tips & Best Practices
+
+1. **Always use latest Wrangler**: `npx wrangler@latest vectorize ...`
+2. **Create metadata indexes first**: Before any vector insertion
+3. **Test with small data**: Use `--count=10` when listing/testing
+4. **Batch operations**: Use Workers for bulk operations (faster than CLI)
+5. **Monitor vector count**: Use `info` command to track index size
+6. **Verify before delete**: Always check with `get` before `delete`
+
+## Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Wrangler version 3.71.0 required" | Old Wrangler | Update: `npm install -g wrangler@latest` |
+| "Vector dimensions do not match" | Wrong embedding size | Check model output dimensions |
+| "Metadata property not indexed" | Metadata index missing | Create metadata index before querying |
+| "Index name already exists" | Duplicate name | Use different name or delete old index |
+| "Invalid filter syntax" | Malformed JSON filter | Check JSON syntax and operators |
+
+## See Also
+
+- [Index Operations](./index-operations.md)
+- [Vector Operations](./vector-operations.md)
+- [Metadata Guide](./metadata-guide.md)
+- [Official Wrangler Docs](https://developers.cloudflare.com/workers/wrangler/commands/#vectorize)