wrangler vectorize - Cloudflare Workers SDK

Vectorize is Cloudflare’s vector database that enables you to build full-stack AI applications. Use these commands to manage your vector indexes and perform vector operations.

create

Create a new Vectorize index.

wrangler vectorize create <name> [options]

name

string

required

The name of the Vectorize index to create (must be unique)

Configuration Options

You must provide either a preset OR both dimensions and metric:

--preset

string

The name of a preset representing an embeddings model. Vectorize will configure the dimensions and distance metric for you.Valid values:

@cf/baai/bge-small-en-v1.5
@cf/baai/bge-base-en-v1.5
@cf/baai/bge-large-en-v1.5
openai/text-embedding-ada-002
cohere/embed-multilingual-v2.0

--dimensions

number

The dimension size to configure this index for, based on the output dimensions of your ML model

--metric

string

The distance metric to use for searching within the index.Valid values: euclidean, cosine, dot-product

--description

string

An optional description for this index

Output Options

--json

boolean

default:"false"

Return output as clean JSON

Worker Binding Options

--binding

string

The binding name of this resource in your Worker

--update-config

boolean

Automatically update your config file with the newly added resource

Examples

Using a preset

wrangler vectorize create my-index --preset="@cf/baai/bge-base-en-v1.5"

Using custom dimensions and metric

wrangler vectorize create my-index --dimensions=768 --metric=cosine

With description

wrangler vectorize create my-index \
  --preset="openai/text-embedding-ada-002" \
  --description="Product embeddings for search"

delete

Delete a Vectorize index.

wrangler vectorize delete <name> [options]

name

string

required

The name of the Vectorize index to delete

Options

--force

boolean

default:"false"

Skip confirmation (alias: -y)

Example

wrangler vectorize delete my-index

Deleting an index permanently removes all vectors and metadata. This operation cannot be undone.

list

List all Vectorize indexes in your account.

wrangler vectorize list [options]

Options

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize list

Displays a table with:

Index name
Dimensions
Distance metric
Description
Created date
Modified date

get

Get details about a specific Vectorize index.

wrangler vectorize get <name> [options]

name

string

required

The name of the Vectorize index

Options

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize get my-index

info

Get additional details about an index including vector count and processing status.

wrangler vectorize info <name> [options]

name

string

required

The name of the Vectorize index

Options

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize info my-index

Displays:

Dimensions
Vector count
Processed up to mutation ID
Processed up to datetime

insert

Insert vectors into a Vectorize index from a file.

wrangler vectorize insert <name> [options]

name

string

required

The name of the Vectorize index

Options

--file

string

required

A file containing line separated JSON (ndjson) vector objects

--batch-size

number

default:"5000"

Number of vector records to include when sending to the Cloudflare API

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize insert my-index --file=vectors.ndjson

Vector File Format

The file should be in NDJSON format (newline-delimited JSON), with each line containing a vector object:

{"id": "1", "values": [0.1, 0.2, 0.3], "metadata": {"text": "example"}}
{"id": "2", "values": [0.4, 0.5, 0.6], "metadata": {"text": "another example"}}

Insert operations are enqueued and processed asynchronously. Use the mutation ID returned to track processing status.

upsert

Upsert (insert or update) vectors into a Vectorize index from a file.

wrangler vectorize upsert <name> [options]

name

string

required

The name of the Vectorize index

Options

--file

string

required

A file containing line separated JSON (ndjson) vector objects

--batch-size

number

default:"5000"

Number of vector records to include in a single upsert batch when sending to the Cloudflare API

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize upsert my-index --file=vectors.ndjson --batch-size=1000

query

Query a Vectorize index to find similar vectors.

wrangler vectorize query <name> [options]

name

string

required

The name of the Vectorize index

Query Input Options

You must provide either --vector OR --vector-id (but not both):

--vector

number[]

Vector values to query the index with. Provide as space-separated numbers.

--vector-id

string

Identifier for a vector in the index against which the index should be queried

Query Options

--top-k

number

default:"5"

The number of results (nearest neighbors) to return

--return-values

boolean

default:"false"

Specify if the vector values should be included in the results

--return-metadata

string

default:"none"

Specify if the vector metadata should be included in the results.Valid values: all, indexed, none

--namespace

string

Filter the query results based on this namespace

--filter

string

Filter the query results based on metadata. Provide as a JSON string.

Examples

Query by vector

wrangler vectorize query my-index --vector 0.1 0.2 0.3 0.4 --top-k=10

Query by vector ID

wrangler vectorize query my-index --vector-id="vector-123" --top-k=5

Query with metadata

wrangler vectorize query my-index \
  --vector 0.1 0.2 0.3 \
  --return-metadata=all \
  --return-values

Query from file

wrangler vectorize query my-index --vector $(jq -r '.[]' data.json | xargs)

Query with filter

wrangler vectorize query my-index \
  --vector 0.1 0.2 0.3 \
  --filter '{"category": "product", "price": {"$lt": 100}}'

get-by-ids

Get specific vectors from an index by their IDs.

wrangler vectorize get-by-ids <name> [options]

name

string

required

The name of the Vectorize index

Options

--ids

string[]

required

Vector identifiers to fetch from the index. Provide as space-separated values.

Example

wrangler vectorize get-by-ids my-index --ids vector-1 vector-2 vector-3

delete-by-ids

Delete specific vectors from an index by their IDs.

wrangler vectorize delete-by-ids <name> [options]

name

string

required

The name of the Vectorize index

Options

--ids

string[]

required

Vector identifiers to delete from the index. Provide as space-separated values.

Example

wrangler vectorize delete-by-ids my-index --ids vector-1 vector-2 vector-3

Delete operations are enqueued and processed asynchronously. Use the mutation ID returned to track processing status.

Metadata Indexes

Metadata indexes enable efficient filtering on vector metadata properties.

create-metadata-index

Enable metadata filtering on a specified property.

wrangler vectorize create-metadata-index <name> [options]

name

string

required

The name of the Vectorize index

Options

--property-name

string

required

The name of the metadata property to index

--type

string

required

The type of metadata property to index.Valid values: string, number, boolean

Example

wrangler vectorize create-metadata-index my-index \
  --property-name="category" \
  --type="string"

list-metadata-index

List metadata properties on which filtering is enabled.

wrangler vectorize list-metadata-index <name> [options]

name

string

required

The name of the Vectorize index

Options

--json

boolean

default:"false"

Return output as clean JSON

Example

wrangler vectorize list-metadata-index my-index

delete-metadata-index

Delete a metadata index.

wrangler vectorize delete-metadata-index <name> [options]

name

string

required

The name of the Vectorize index

Options

--property-name

string

required

The name of the metadata property to remove from indexing

Example

wrangler vectorize delete-metadata-index my-index --property-name="category"

Configuration

Add a Vectorize index to your Worker:

wrangler.json

{
  "vectorize": [
    {
      "binding": "VECTORIZE",
      "index_name": "my-index"
    }
  ]
}

Use it in your Worker:

export default {
  async fetch(request, env) {
    // Insert vectors
    const vectors = [
      {
        id: '1',
        values: [0.1, 0.2, 0.3],
        metadata: { text: 'Hello world' }
      }
    ];
    
    await env.VECTORIZE.insert(vectors);
    
    // Query vectors
    const results = await env.VECTORIZE.query(
      [0.1, 0.2, 0.3],
      { topK: 5, returnMetadata: true }
    );
    
    return Response.json(results);
  },
};

Metadata Filtering

When querying vectors, you can filter results based on metadata:

Basic Equality

{
  "category": "product",
  "active": true
}

Comparison Operators

{
  "price": { "$lt": 100 },
  "rating": { "$gte": 4.5 }
}

Supported operators:

$eq - equals
$ne - not equals
$lt - less than
$lte - less than or equal
$gt - greater than
$gte - greater than or equal

Array Operators

{
  "category": { "$in": ["electronics", "computers"] },
  "tag": { "$nin": ["deprecated", "archived"] }
}

Nested Properties

{
  "user.age": { "$gte": 18 },
  "user.country": "US"
}

Rate Limits and Batch Processing

Insert/Upsert operations are limited to 5,000 vectors per batch by default
Total upload limit during beta: 100,000 vectors per run
Operations are processed asynchronously - use mutation IDs to track progress
The global Cloudflare API rate limit is 1,200 requests per 5 minutes

Best Practices

Choose the right metric: Use cosine for normalized vectors, euclidean for absolute distances, and dot-product for similarity scores.
Index metadata selectively: Only create metadata indexes for properties you’ll filter on frequently.
Batch operations: Use larger batch sizes (up to 5,000) for better performance when inserting many vectors.
Use presets when possible: Presets automatically configure optimal settings for popular embedding models.
Monitor mutations: Track mutation IDs to ensure your insert/upsert/delete operations complete successfully.

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

​create

​Configuration Options

​Output Options

​Worker Binding Options

​Examples

​Using a preset

​Using custom dimensions and metric

​With description

​delete

​Options

​Example

​list

​Options

​Example

​get

​Options

​Example

​info

​Options

​Example

​insert

​Options

​Example

​Vector File Format

​upsert

​Options

​Example

​query

​Query Input Options

​Query Options

​Examples

​Query by vector

​Query by vector ID

​Query with metadata

​Query from file

​Query with filter

​get-by-ids

​Options

​Example

​delete-by-ids

​Options

​Example

​Metadata Indexes

​Options

​Example

​Options

​Example

​Options

​Example

​Configuration

​Metadata Filtering

​Basic Equality

​Comparison Operators

​Array Operators

​Nested Properties

​Rate Limits and Batch Processing

​Best Practices

Build docs developers (and LLMs) love

create

Configuration Options

Output Options

Worker Binding Options

Examples

Using a preset

Using custom dimensions and metric

With description

delete

Options

Example

list

Options

Example

get

Options

Example

info

Options

Example

insert

Options

Example

Vector File Format

upsert

Options

Example

query

Query Input Options

Query Options

Examples

Query by vector

Query by vector ID

Query with metadata

Query from file

Query with filter

get-by-ids

Options

Example

delete-by-ids

Options

Example

Metadata Indexes

Options

Example

Options

Example

Options

Example

Configuration

Metadata Filtering

Basic Equality

Comparison Operators

Array Operators

Nested Properties

Rate Limits and Batch Processing

Best Practices