From 8d9302175c0244fa67d975ca2e7aeb09aa3d10a3 Mon Sep 17 00:00:00 2001
From: Garvit Gupta <garvit@cloudflare.com>
Date: Fri, 23 Aug 2024 00:32:40 -0500
Subject: [PATCH 1/8] VS-273: Update Vectorize Dev Docs according to V2 Spec

---
 .../best-practices/create-indexes.mdx         |  38 ++-
 .../best-practices/insert-vectors.mdx         |  30 ++-
 .../best-practices/query-vectors.mdx          |  75 +++---
 .../docs/vectorize/get-started/embeddings.mdx |  36 +--
 .../docs/vectorize/get-started/intro.mdx      | 237 +++++++++++++-----
 .../docs/vectorize/platform/limits.mdx        |  58 ++---
 .../docs/vectorize/reference/client-api.mdx   |  32 ++-
 .../reference/metadata-filtering.mdx          |  50 ++--
 .../reference/transition-vectorize-legacy.mdx |  76 ++++++
 .../partials/vectorize/vectorize-legacy.mdx   |  11 +
 .../vectorize/vectorize-wrangler-version.mdx  |   5 +-
 11 files changed, 456 insertions(+), 192 deletions(-)
 create mode 100644 src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
 create mode 100644 src/content/partials/vectorize/vectorize-legacy.mdx

diff --git a/src/content/docs/vectorize/best-practices/create-indexes.mdx b/src/content/docs/vectorize/best-practices/create-indexes.mdx
index 6d6ec81827d5fd..f1519ed93d10aa 100644
--- a/src/content/docs/vectorize/best-practices/create-indexes.mdx
+++ b/src/content/docs/vectorize/best-practices/create-indexes.mdx
@@ -23,11 +23,7 @@ The configuration of an index cannot be changed after creation.
 
 <Render file="vectorize-wrangler-version" />
 
-:::note[Using Vectorize v1?]
-
-Please use the 'wrangler vectorize --deprecated-v1' flag to create, get, list, delete and insert vectors into legacy Vectorize v1 indexes.
-
-:::
+<Render file="vectorize-legacy" />
 
 To create an index with `wrangler`:
 
@@ -41,6 +37,38 @@ To create an index that can accept vector embeddings from Worker's AI's [`@cf/ba
 npx wrangler vectorize create your-index-name --dimensions=768 --metric=cosine
 ```
 
+### HTTP API
+
+Vectorize also supports creating indexes via [REST API](/api/operations/vectorize-create-vectorize-index).
+
+For example, to create an index directly from a Python script:
+
+```py
+import requests
+
+url = "https://api.cloudflare.com/client/v4/accounts/{}/vectorize/v2/indexes".format("your-account-id")
+
+headers = {
+    "Authorization": "Bearer <your-api-token>"
+}
+
+body = {
+	"name": "demo-index"
+	"description": "some index description",
+  "config": {
+    "dimensions": 1024,
+    "metric": "euclidean"
+  },
+}
+
+resp = requests.post(url, headers=headers, json=body)
+
+print('Status Code:', resp.status_code)
+print('Response JSON:', resp.json())
+```
+
+This script should print the response with a status code 201, along with a JSON response body indicating the creation of an index with the provided configuration.
+
 ## Dimensions
 
 Dimensions are determined from the output size of the machine learning (ML) model used to generate them, and are a function of how the model encodes and describes features into a vector embedding.
diff --git a/src/content/docs/vectorize/best-practices/insert-vectors.mdx b/src/content/docs/vectorize/best-practices/insert-vectors.mdx
index 9fb3b43e2a0202..4f3124a71eef20 100644
--- a/src/content/docs/vectorize/best-practices/insert-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/insert-vectors.mdx
@@ -9,6 +9,16 @@ import { Render } from "~/components";
 
 Vectorize indexes allow you to insert vectors at any point: Vectorize will optimize the index behind the scenes to ensure that vector search remains efficient, even as new vectors are added or existing vectors updated.
 
+:::note[Insert vs Upsert]
+
+If the same vector id is _inserted_ twice in a Vectorize index, the index would reflect the vector that was added first.
+
+If the same vector id is _upserted_ twice in a Vectorize index, the index would reflect the vector that was added second.
+
+Use the upsert operation if you want to overwrite the vector value for a vector id that already exists in an index.
+
+:::
+
 ## Supported vector formats
 
 Vectorize supports vectors in three formats:
@@ -34,7 +44,7 @@ Metadata can be used to:
 For example, a vector embedding representing an image could include the path to the [R2 object](/r2/) it was generated from, the format, and a category lookup:
 
 ```ts
-{ id: '1', values: [32.4, 74.1, 3.2], metadata: { path: 'r2://bucket-name/path/to/image.png', format: 'png', category: 'profile_image' } }
+{ id: '1', values: [32.4, 74.1, 3.2, ...], metadata: { path: 'r2://bucket-name/path/to/image.png', format: 'png', category: 'profile_image' } }
 ```
 
 ## Namespaces
@@ -43,9 +53,9 @@ Namespaces provide a way to segment the vectors within your index. For example,
 
 To associate vectors with a namespace, you can optionally provide a `namespace: string` value when performing an insert or upsert operation. When querying, you can pass the namespace to search within as an optional parameter to your query.
 
-A namespace can be up to 63 characters (bytes) in length and you can have up to 1,000 namespaces per index. Refer to the [Limits](/vectorize/platform/limits/) documentation for more details.
+A namespace can be up to 64 characters (bytes) in length and you can have up to 1,000 namespaces per index. Refer to the [Limits](/vectorize/platform/limits/) documentation for more details.
 
-When a namespace is provided, only vectors within that namespace are used for the search. Namespace filtering is applied before vector search, not after.
+When a namespace is specified in a query operation, only vectors within that namespace are used for the search. Namespace filtering is applied before vector search, not after.
 
 To insert vectors with a namespace:
 
@@ -56,17 +66,17 @@ To insert vectors with a namespace:
 const sampleVectors: Array<VectorizeVector> = [
 	{
 		id: "1",
-		values: [32.4, 74.1, 3.2],
+		values: [32.4, 74.1, 3.2, ...],
 		namespace: "text",
 	},
 	{
 		id: "2",
-		values: [15.1, 19.2, 15.8],
+		values: [15.1, 19.2, 15.8, ...],
 		namespace: "images",
 	},
 	{
 		id: "3",
-		values: [0.16, 1.2, 3.8],
+		values: [0.16, 1.2, 3.8, ...],
 		namespace: "pdfs",
 	},
 ];
@@ -97,17 +107,17 @@ Use the `insert()` and `upsert()` methods available on an index from within a Cl
 const sampleVectors: Array<VectorizeVector> = [
 	{
 		id: "1",
-		values: [32.4, 74.1, 3.2],
+		values: [32.4, 74.1, 3.2, ...],
 		metadata: { url: "/products/sku/13913913" },
 	},
 	{
 		id: "2",
-		values: [15.1, 19.2, 15.8],
+		values: [15.1, 19.2, 15.8, ...],
 		metadata: { url: "/products/sku/10148191" },
 	},
 	{
 		id: "3",
-		values: [0.16, 1.2, 3.8],
+		values: [0.16, 1.2, 3.8, ...],
 		metadata: { url: "/products/sku/97913813" },
 	},
 ];
@@ -154,7 +164,7 @@ For example, to insert embeddings in [NDJSON format](#workers-api) directly from
 ```py
 import requests
 
-url = "https://api.cloudflare.com/client/v4/accounts/{}/vectorize/indexes/{}/insert".format("your-account-id", "index-name")
+url = "https://api.cloudflare.com/client/v4/accounts/{}/vectorize/v2/indexes/{}/insert".format("your-account-id", "index-name")
 
 headers = {
     "Authorization": "Bearer <your-api-token>"
diff --git a/src/content/docs/vectorize/best-practices/query-vectors.mdx b/src/content/docs/vectorize/best-practices/query-vectors.mdx
index 6428dc528a6e9b..2a0c6b7284a5cc 100644
--- a/src/content/docs/vectorize/best-practices/query-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/query-vectors.mdx
@@ -3,7 +3,6 @@ title: Query vectors
 pcx_content_type: concept
 sidebar:
   order: 5
-
 ---
 
 Querying an index, or vector search, enables you to search an index by providing an input vector and returning the nearest vectors based on the [configured distance metric](/vectorize/best-practices/create-indexes/#distance-metrics).
@@ -17,52 +16,54 @@ To pass a vector as a query to an index, use the `query()` method on the index i
 A query vector is either an array of JavaScript numbers, 32-bit floating point or 64-bit floating point numbers: `number[]`, `Float32Array`, or `Float64Array`. Unlike when [inserting vectors](/vectorize/best-practices/insert-vectors/), a query vector does not need an ID or metadata.
 
 ```ts
-let queryVector = [54.8, 5.5, 3.1];
+let queryVector = [54.8, 5.5, 3.1, ...]; // query vector dimensions should match the Vectorize index dimension being queried
 let matches = await env.YOUR_INDEX.query(queryVector);
 ```
 
-This would return a set of matches resembling the following, based on a `cosine` distance metric:
+This would return a set of matches resembling the following, based on the distance metric configured for the Vectorize index. Example response with `cosine` distance metric:
 
 ```json
 {
-  "matches": {
-    "count": 3,
-    "matches": [
-      { "score": 0.999909486, "id": "5" },
-      { "score": 0.789848214, "id": "4" },
-      { "score": 0.720476967, "id": "4444" }
-    ]
-  }
+	"matches": {
+		"count": 5,
+		"matches": [
+			{ "score": 0.999909486, "id": "5" },
+			{ "score": 0.789848214, "id": "4" },
+			{ "score": 0.720476967, "id": "4444" },
+			{ "score": 0.463884663, "id": "6" },
+			{ "score": 0.378282232, "id": "1" }
+		]
+	}
 }
 ```
 
 You can optionally change the number of results returned and/or whether results should include metadata and values:
 
 ```ts
-let queryVector = [54.8, 5.5, 3.1];
-// topK defaults to 3; returnValues defaults to false; returnMetadata defaults to false
+let queryVector = [54.8, 5.5, 3.1, ...]; // query vector dimensions should match the Vectorize index dimension being queried
+// topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
 let matches = await env.YOUR_INDEX.query(queryVector, {
-  topK: 1,
-  returnValues: true,
-  returnMetadata: true,
+	topK: 1,
+	returnValues: true,
+	returnMetadata: "all",
 });
 ```
 
-This would return a set of matches resembling the following, based on a `cosine` distance metric:
+This would return a set of matches resembling the following, based on the distance metric configured for the Vectorize index. Example response with `cosine` distance metric:
 
 ```json
 {
-  "matches": {
-    "count": 1,
-    "matches": [
-      {
-        "score": 0.999909486,
-        "id": "5",
-        "values": [58.79999923706055, 6.699999809265137, 3.4000000953674316],
-        "metadata": { "url": "/products/sku/55519183" }
-      }
-    ]
-  }
+	"matches": {
+		"count": 1,
+		"matches": [
+			{
+				"score": 0.999909486,
+				"id": "5",
+				"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316, ...],
+				"metadata": { "url": "/products/sku/55519183" }
+			}
+		]
+	}
 }
 ```
 
@@ -74,16 +75,16 @@ If you are generating embeddings from a [Workers AI](/workers-ai/models/#text-em
 
 ```ts
 interface EmbeddingResponse {
-  shape: number[];
-  data: number[][];
+	shape: number[];
+	data: number[][];
 }
 
 let userQuery = "a query from a user or service";
 const queryVector: EmbeddingResponse = await env.AI.run(
-  "@cf/baai/bge-base-en-v1.5",
-  {
-    text: [userQuery],
-  }
+	"@cf/baai/bge-base-en-v1.5",
+	{
+		text: [userQuery],
+	},
 );
 ```
 
@@ -107,8 +108,8 @@ const openai = new OpenAI({ apiKey: env.YOUR_OPENAPI_KEY });
 let userQuery = "a query from a user or service";
 
 let embeddingResponse = await openai.embeddings.create({
-  input: userQuery,
-  model: "text-embedding-ada-002",
+	input: userQuery,
+	model: "text-embedding-ada-002",
 });
 ```
 
@@ -116,6 +117,6 @@ Similar to Workers AI, you will need to provide the vector embedding itself (`.e
 
 ```ts
 let matches = await env.TEXT_EMBEDDINGS.query(embeddingResponse.embedding[0], {
-  topK: 1,
+	topK: 1,
 });
 ```
diff --git a/src/content/docs/vectorize/get-started/embeddings.mdx b/src/content/docs/vectorize/get-started/embeddings.mdx
index 94f5ea673111a7..e1d692191a8f13 100644
--- a/src/content/docs/vectorize/get-started/embeddings.mdx
+++ b/src/content/docs/vectorize/get-started/embeddings.mdx
@@ -77,11 +77,7 @@ To create your first Vectorize index, change into the directory you just created
 cd embeddings-tutorial
 ```
 
-:::note[Using Vectorize v1?]
-
-Please use the 'wrangler vectorize --deprecated-v1' flag to create, get, list, delete and insert vectors into legacy Vectorize v1 indexes.
-
-:::
+<Render file="vectorize-legacy" />
 
 To create an index, use the `wrangler vectorize create` command and provide a name for the index. A good index name is:
 
@@ -103,7 +99,7 @@ npx wrangler vectorize create embeddings-index --dimensions=768 --metric=cosine
 ✅ Successfully created index 'embeddings-index'
 
 [[vectorize]]
-binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
+binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
 index_name = "embeddings-index"
 ```
 
@@ -117,13 +113,13 @@ To bind your index to your Worker, add the following to the end of your `wrangle
 
 ```toml
 [[vectorize]]
-binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
+binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
 index_name = "embeddings-index"
 ```
 
 Specifically:
 
-- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE_INDEX`.
+- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
 - The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_INDEX"` or `binding = "PROD_SEARCH_INDEX"` would both be valid names for the binding.
 - Your binding is available in your Worker at `env.<BINDING_NAME>` and the Vectorize [client API](/vectorize/reference/client-api/) is exposed on this binding for use within your Workers application.
 
@@ -135,7 +131,7 @@ From within the `embeddings-tutorial` directory, open your `wrangler.toml` file
 
 ```toml
 [[vectorize]]
-binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
+binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
 index_name = "embeddings-index"
 
 [ai]
@@ -148,11 +144,11 @@ With Workers AI ready, you can write code in your Worker.
 
 To write code in your Worker, go to your `embeddings-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.
 
-Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE_INDEX`:
+Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:
 
 ```typescript
 export interface Env {
-	VECTORIZE_INDEX: VectorizeIndex;
+	VECTORIZE: Vectorize;
 	AI: Ai;
 }
 interface EmbeddingResponse {
@@ -195,7 +191,7 @@ export default {
 				id++;
 			});
 
-			let inserted = await env.VECTORIZE_INDEX.upsert(vectors);
+			let inserted = await env.VECTORIZE.upsert(vectors);
 			return Response.json(inserted);
 		}
 
@@ -208,12 +204,12 @@ export default {
 			},
 		);
 
-		let matches = await env.VECTORIZE_INDEX.query(queryVector.data[0], {
+		let matches = await env.VECTORIZE.query(queryVector.data[0], {
 			topK: 1,
 		});
 		return Response.json({
 			// Expect a vector ID. 1 to be your top match with a score of
-			// ~0.896888444
+			// ~0.89693683
 			// This tutorial uses a cosine distance metric, where the closer to one,
 			// the more similar.
 			matches: matches,
@@ -252,7 +248,17 @@ With the URL for your deployed Worker (for example,`https://embeddings-tutorial.
 This should return the following JSON:
 
 ```json
-{ "matches": { "count": 1, "matches": [{ "score": 0.896888444, "id": "1" }] } }
+{
+	"matches": {
+		"count": 1,
+		"matches": [
+			{
+				"id": "1",
+				"score": 0.89693683
+			}
+		]
+	}
+}
 ```
 
 Extend this example by:
diff --git a/src/content/docs/vectorize/get-started/intro.mdx b/src/content/docs/vectorize/get-started/intro.mdx
index 47699fd167a43c..30161fb2533757 100644
--- a/src/content/docs/vectorize/get-started/intro.mdx
+++ b/src/content/docs/vectorize/get-started/intro.mdx
@@ -82,11 +82,7 @@ To create your first Vectorize index, change into the directory you just created
 cd vectorize-tutorial
 ```
 
-:::note[Using Vectorize v1?]
-
-Please use the 'wrangler vectorize --deprecated-v1' flag to create, get, list, delete and insert vectors into legacy Vectorize v1 indexes.
-
-:::
+<Render file="vectorize-legacy" />
 
 To create an index, you will need to use the `wrangler vectorize create` command and provide a name for the index. A good index name is:
 
@@ -94,21 +90,23 @@ To create an index, you will need to use the `wrangler vectorize create` command
 - Descriptive of the use-case and environment. For example, "production-doc-search" or "dev-recommendation-engine".
 - Only used for describing the index, and is not directly referenced in code.
 
-In addition, you will need to define both the `dimensions` of the vectors you will store in the index, as well as the distance `metric` used to determine similar vectors when creating the index. A `metric` can be Euclidean, cosine, or dot product. **This configuration cannot be changed later**, as a vector database is configured for a fixed vector configuration.
+In addition, you will need to define both the `dimensions` of the vectors you will store in the index, as well as the distance `metric` used to determine similar vectors when creating the index. A `metric` can be euclidean, cosine, or dot product. **This configuration cannot be changed later**, as a vector database is configured for a fixed vector configuration.
 
 <Render file="vectorize-wrangler-version" />
 
 Run the following `wrangler vectorize` command:
 
 ```sh
-npx wrangler vectorize create tutorial-index --dimensions=3 --metric=cosine
+npx wrangler vectorize create tutorial-index --dimensions=32 --metric=euclidean
 ```
 
 ```sh output
-✅ Successfully created index 'tutorial-index'
+🚧 Creating index: 'tutorial-index'
+✅ Successfully created a new Vectorize index: 'tutorial-index'
+📋 To start querying from a Worker, add the following binding configuration into 'wrangler.toml':
 
 [[vectorize]]
-binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
+binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
 index_name = "tutorial-index"
 ```
 
@@ -116,65 +114,123 @@ The command above will create a new vector database, and output the [binding](/w
 
 ## 3. Bind your Worker to your index
 
-You must create a binding for your Worker to connect to your Vectorize index. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like Vectorize or R2, from Cloudflare Workers. You create bindings by updating your `wrangler.toml` file.
+You must create a binding for your Worker to connect to your Vectorize index. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like Vectorize or R2, from Cloudflare Workers. You create bindings by updating the worker's `wrangler.toml` file.
 
 To bind your index to your Worker, add the following to the end of your `wrangler.toml` file:
 
 ```toml
 [[vectorize]]
-binding = "VECTORIZE_INDEX" # available in your Worker on env.VECTORIZE_INDEX
+binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
 index_name = "tutorial-index"
 ```
 
 Specifically:
 
-- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE_INDEX`.
+- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
 - The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_INDEX"` or `binding = "PROD_SEARCH_INDEX"` would both be valid names for the binding.
 - Your binding is available in your Worker at `env.<BINDING_NAME>` and the Vectorize [client API](/vectorize/reference/client-api/) is exposed on this binding for use within your Workers application.
 
-## 4. Insert vectors
+## 4. [Optional] Create metadata indexes
+
+Vectorize allows you to add metadata along with vectors into your index, and also provides the ability to to filter on the vector metadata while querying vectors. To do so you would need to specify a metadata field as a "metadata index" for your Vectorize index.
+
+:::note[When to create metadata indexes?]
+
+As of today, the metadata fields on which vectors can be filtered need to be specified before the vectors are inserted, and it is recommended that these metadata fields are specified right after the creation of a Vectorize index.
+
+:::
+
+To enable vector filtering on a metadata field during a query, use a command like:
+
+```sh
+npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
+```
+
+```sh output
+📋 Creating metadata index...
+✅ Successfully enqueued metadata index creation request. Mutation changeset identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
+```
+
+Here `url` is the metadata field on which filtering would be enabled. The `--type` parameter defines the data type for the metadata field; `string`, `number` and `boolean` types are supported.
+
+It typically takes a few seconds for the metadata index to be created. You can check the list of metadata indexes for your Vectorize index by running:
+
+```sh
+npx wrangler vectorize list-metadata-index tutorial-index
+```
+
+```sh output
+📋 Fetching metadata indexes...
+┌──────────────┬────────┐
+│ propertyName │ type   │
+├──────────────┼────────┤
+│ url          │ String │
+└──────────────┴────────┘
+```
+
+## 5. Insert vectors
 
 Before you can query a vector database, you need to insert vectors for it to query against. These vectors would be generated from data (such as text or images) you pass to a machine learning model. However, this tutorial will define static vectors to illustrate how vector search works on its own.
 
 First, go to your `vectorize-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.
 
-Clear the content of `index.ts`, and paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE_INDEX`:
+Clear the content of `index.ts`, and paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:
 
 ```typescript
 export interface Env {
-	// This makes your vector index methods available on env.VECTORIZE_INDEX.*
-	// For example, env.VECTORIZE_INDEX.insert() or query()
-	VECTORIZE_INDEX: VectorizeIndex;
+	// This makes your vector index methods available on env.VECTORIZE.*
+	// For example, env.VECTORIZE.insert() or query()
+	VECTORIZE: Vectorize;
 }
 
-// Sample vectors: 3 dimensions wide.
+// Sample vectors: 32 dimensions wide.
 //
-// Vectors from a machine-learning model are typically ~100 to 1536 dimensions
+// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions
 // wide (or wider still).
 const sampleVectors: Array<VectorizeVector> = [
 	{
 		id: "1",
-		values: [32.4, 74.1, 3.2],
+		values: [
+			0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67,
+			0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27,
+			0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55,
+		],
 		metadata: { url: "/products/sku/13913913" },
 	},
 	{
 		id: "2",
-		values: [15.1, 19.2, 15.8],
+		values: [
+			0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53,
+			0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48,
+			0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53,
+		],
 		metadata: { url: "/products/sku/10148191" },
 	},
 	{
 		id: "3",
-		values: [0.16, 1.2, 3.8],
+		values: [
+			0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
+			0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85,
+			0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48,
+		],
 		metadata: { url: "/products/sku/97913813" },
 	},
 	{
 		id: "4",
-		values: [75.1, 67.1, 29.9],
+		values: [
+			0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66,
+			0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29,
+			0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49,
+		],
 		metadata: { url: "/products/sku/418313" },
 	},
 	{
 		id: "5",
-		values: [58.8, 6.7, 3.4],
+		values: [
+			0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61,
+			0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3,
+			0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53,
+		],
 		metadata: { url: "/products/sku/55519183" },
 	},
 ];
@@ -191,9 +247,9 @@ export default {
 			// Insert some sample vectors into your index
 			// In a real application, these vectors would be the output of a machine learning (ML) model,
 			// such as Workers AI, OpenAI, or Cohere.
-			const inserted = await env.VECTORIZE_INDEX.insert(sampleVectors);
+			const inserted = await env.VECTORIZE.insert(sampleVectors);
 
-			// Return the number of IDs you successfully inserted
+			// Return the mutation identifier for this insert operation
 			return Response.json(inserted);
 		}
 
@@ -210,49 +266,69 @@ In the code above, you:
 
 In the next step, you will expand the Worker to query the index and the vectors you insert.
 
-## 5. Query vectors
+## 6. Query vectors
 
 In this step, you will take a vector representing an incoming query and use it to search your index.
 
 First, go to your `vectorize-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.
 
-Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE_INDEX`:
+Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:
 
 ```typescript
 export interface Env {
-	// This makes our vector index methods available on env.VECTORIZE_INDEX.*
-	// For example, env.VECTORIZE_INDEX.insert() or query()
-	VECTORIZE_INDEX: VectorizeIndex;
+	// This makes your vector index methods available on env.VECTORIZE.*
+	// For example, env.VECTORIZE.insert() or query()
+	VECTORIZE: Vectorize;
 }
 
-// Sample vectors: 3 dimensions wide.
+// Sample vectors: 32 dimensions wide.
 //
-// Vectors from a machine-learning model are typically ~100 to 1536 dimensions
+// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions
 // wide (or wider still).
 const sampleVectors: Array<VectorizeVector> = [
 	{
 		id: "1",
-		values: [32.4, 74.1, 3.2],
+		values: [
+			0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67,
+			0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27,
+			0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55,
+		],
 		metadata: { url: "/products/sku/13913913" },
 	},
 	{
 		id: "2",
-		values: [15.1, 19.2, 15.8],
+		values: [
+			0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53,
+			0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48,
+			0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53,
+		],
 		metadata: { url: "/products/sku/10148191" },
 	},
 	{
 		id: "3",
-		values: [0.16, 1.2, 3.8],
+		values: [
+			0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
+			0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85,
+			0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48,
+		],
 		metadata: { url: "/products/sku/97913813" },
 	},
 	{
 		id: "4",
-		values: [75.1, 67.1, 29.9],
+		values: [
+			0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66,
+			0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29,
+			0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49,
+		],
 		metadata: { url: "/products/sku/418313" },
 	},
 	{
 		id: "5",
-		values: [58.8, 6.7, 3.4],
+		values: [
+			0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61,
+			0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3,
+			0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53,
+		],
 		metadata: { url: "/products/sku/55519183" },
 	},
 ];
@@ -269,9 +345,9 @@ export default {
 			// Insert some sample vectors into your index
 			// In a real application, these vectors would be the output of a machine learning (ML) model,
 			// such as Workers AI, OpenAI, or Cohere.
-			let inserted = await env.VECTORIZE_INDEX.insert(sampleVectors);
+			let inserted = await env.VECTORIZE.insert(sampleVectors);
 
-			// Return the number of IDs we successfully inserted
+			// Return the mutation identifier for this insert operation
 			return Response.json(inserted);
 		}
 
@@ -281,8 +357,12 @@ export default {
 		// vector database" - and transform it into a vector embedding first.
 		//
 		// In this example, you will construct a vector that should
-		// match vector id #5
-		const queryVector: Array<number> = [54.8, 5.5, 3.1];
+		// match vector id #4
+		const queryVector: Array<number> = [
+			0.13, 0.25, 0.44, 0.53, 0.62, 0.41, 0.59, 0.68, 0.29, 0.82, 0.37, 0.5,
+			0.74, 0.46, 0.57, 0.64, 0.28, 0.61, 0.73, 0.35, 0.78, 0.58, 0.42, 0.32,
+			0.77, 0.65, 0.49, 0.54, 0.31, 0.29, 0.71, 0.57,
+		]; // vector of dimensions 32
 
 		// Query your index and return the three (topK = 3) most similar vector
 		// IDs with their similarity score.
@@ -290,16 +370,16 @@ export default {
 		// By default, vector values are not returned, as in many cases the
 		// vector id and scores are sufficient to map the vector back to the
 		// original content it represents.
-		const matches = await env.VECTORIZE_INDEX.query(queryVector, {
+		const matches = await env.VECTORIZE.query(queryVector, {
 			topK: 3,
 			returnValues: true,
-			returnMetadata: true,
+			returnMetadata: "all",
 		});
 
 		return Response.json({
-			// This will return the closest vectors: you will notice that the vector
-			// with id = 5 has the highest score (closest to 1.0) as the
-			// distance between it and our query vector is the smallest.
+			// This will return the closest vectors: the vectors are arranged according
+			// to their scores. Vectors that are more similar would show up near the top.
+			// In this example, Vector id #4 would turn out to be the most similar to the queried vector.
 			// You return the full set of matches so you can check the possible scores.
 			matches: matches,
 		});
@@ -307,7 +387,7 @@ export default {
 } satisfies ExportedHandler<Env>;
 ```
 
-## 6. Deploy your Worker
+## 7. Deploy your Worker
 
 Before deploying your Worker globally, log in with your Cloudflare account by running:
 
@@ -325,7 +405,7 @@ npx wrangler deploy
 
 Once deployed, preview your Worker at `https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev`.
 
-## 7. Query your index
+## 8. Query your index
 
 To insert vectors and then query them, use the URL for your deployed Worker, such as `https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/`. Open your browser and:
 
@@ -333,14 +413,33 @@ To insert vectors and then query them, use the URL for your deployed Worker, suc
 
 ```json
 // https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/insert
-{ "count": 5, "ids": [1, 2, 3, 4, 5] }
+{
+	"mutationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+}
 ```
 
-Subsequent visits will return `count:0` as you cannot `insert()` the same vector IDs.
+The mutationId here refers to a unique identifier that corresponds to this asynchronous insert operation. Typically it takes a few seconds for inserted vectors to be available for querying.
 
-2. Query your index - expect your query vector of `[54.8, 5.5, 3.1]` to be closest to vector ID `5` by visiting the root path of `/` . This query will return the three (`topK: 3`) closest matches, as well as their vector values and metadata.
+You can use the index info operation to check the last processed mutation:
 
-You will notice that `id: 5` has a `score` of `0.999909486`. Because you are using `cosine` as our distance metric, the closer the score to `1.0`, the closer your vectors are.
+```sh
+npx wrangler vectorize info tutorial-index
+```
+
+```sh output
+📋 Fetching index info...
+┌────────────┬─────────────┬──────────────────────────────────────┬──────────────────────────┐
+│ dimensions │ vectorCount │ processedUpToMutation                │ processedUpToDatetime    │
+├────────────┼─────────────┼──────────────────────────────────────┼──────────────────────────┤
+│ 32         │ 5           │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ YYYY-MM-DDThh:mm:ss.SSSZ │
+└────────────┴─────────────┴──────────────────────────────────────┴──────────────────────────┘
+```
+
+Subsequent inserts using the same vector ids will return a mutation id, but it would not change the index vector count since the same vector ids cannot be inserted twice. You will need to use an `upsert` operation instead to update the vector values for an id that already exists in an index.
+
+2. Query your index - expect your query vector of `[0.13, 0.25, 0.44, ...]` to be closest to vector ID `4` by visiting the root path of `/` . This query will return the three (`topK: 3`) closest matches, as well as their vector values and metadata.
+
+You will notice that `id: 4` has a `score` of `0.46348256`. Because you are using `euclidean` as our distance metric, the closer the score to `0.0`, the closer your vectors are.
 
 ```json
 // https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/
@@ -349,25 +448,37 @@ You will notice that `id: 5` has a `score` of `0.999909486`. Because you are usi
 		"count": 3,
 		"matches": [
 			{
-				"id": "5",
-				"score": 0.999909486,
-				"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316],
+				"id": "4",
+				"score": 0.46348256,
+				"values": [
+					0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39,
+					0.66, 0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41,
+					0.29, 0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49
+				],
 				"metadata": {
-					"url": "/products/sku/55519183"
+					"url": "/products/sku/418313"
 				}
 			},
 			{
-				"id": "4",
-				"score": 0.789848214,
-				"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
+				"id": "3",
+				"score": 0.52920616,
+				"values": [
+					0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
+					0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39,
+					0.85, 0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48
+				],
 				"metadata": {
-					"url": "/products/sku/418313"
+					"url": "/products/sku/97913813"
 				}
 			},
 			{
 				"id": "2",
-				"score": 0.611976262,
-				"values": [15.100000381469727, 19.200000762939453, 15.800000190734863],
+				"score": 0.6337869,
+				"values": [
+					0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41,
+					0.53, 0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57,
+					0.62, 0.48, 0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53
+				],
 				"metadata": {
 					"url": "/products/sku/10148191"
 				}
diff --git a/src/content/docs/vectorize/platform/limits.mdx b/src/content/docs/vectorize/platform/limits.mdx
index f63ad01875df15..3ede25198df2e8 100644
--- a/src/content/docs/vectorize/platform/limits.mdx
+++ b/src/content/docs/vectorize/platform/limits.mdx
@@ -3,50 +3,46 @@ pcx_content_type: concept
 title: Limits
 sidebar:
   order: 2
-
 ---
 
 :::note
 
-
 Many of these limits will increase during Vectorize's [public beta](/workers/platform/betas/). Refer to the [changelog](/vectorize/platform/changelog/) or join the [`#vectorize-beta`](https://discord.cloudflare.com/) channel in the Cloudflare Developer Discord to keep up to date with changes.
 
-
 :::
 
 The following limits apply to accounts, indexes and vectors (as specified):
 
-| Feature                           | Current Limit                                                        |
-| --------------------------------- | -------------------------------------------                          |
-| Indexes per account               | 100 indexes <sup>beta</sup>                                          |
-| Maximum dimensions per vector     | 1536 dimensions <sup>beta</sup>                                      |
-| Maximum vector ID length          | 64 bytes                                                             |
-| Metadata per vector               | 10KiB <sup>beta</sup>                                                |
-| Maximum returned results (`topK`) with values or metadata| 20   <sup>beta</sup>                          |
-| Maximum returned results (`topK`) without values and metadata | 100   <sup>beta</sup>                    |
-| Maximum upsert batch size (per batch) | 1000 <sup>beta</sup> (Workers) / 5000 <sup>beta</sup> (HTTP API) |
-| Maximum index name length         | 64 bytes                                                             |
-| Maximum vectors per index         | 5,000,000 <sup>beta</sup>                                            |
-| Maximum namespaces per index      | 1000 namespaces  <sup>beta</sup>                                     |
-| Maximum namespace name length     | 64 bytes                                                             |
-| Maximum vectors upload size       | 100  MB                                                              |
+| Feature                                                       | Current Limit                                                    |
+| ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Indexes per account                                           | 100 indexes <sup>beta</sup>                                      |
+| Maximum dimensions per vector                                 | 1536 dimensions <sup>beta</sup>                                  |
+| Maximum vector ID length                                      | 64 bytes                                                         |
+| Metadata per vector                                           | 10KiB <sup>beta</sup>                                            |
+| Maximum returned results (`topK`) with values or metadata     | 20 <sup>beta</sup>                                               |
+| Maximum returned results (`topK`) without values and metadata | 100 <sup>beta</sup>                                              |
+| Maximum upsert batch size (per batch)                         | 1000 <sup>beta</sup> (Workers) / 5000 <sup>beta</sup> (HTTP API) |
+| Maximum index name length                                     | 64 bytes                                                         |
+| Maximum vectors per index                                     | 5,000,000 <sup>beta</sup>                                        |
+| Maximum namespaces per index                                  | 1000 namespaces <sup>beta</sup>                                  |
+| Maximum namespace name length                                 | 64 bytes                                                         |
+| Maximum vectors upload size                                   | 100 MB                                                           |
 
 <sup>beta</sup> This limit is beta only and is expected to increase over time.
 
-
-# Limits v1 (deprecated)
+# Limits V1 (deprecated)
 
 The following limits apply to accounts, indexes and vectors (as specified):
 
-| Feature                               | Current Limit                                                    |
-| ------------------------------------- | ---------------------------------------------------------------- |
-| Indexes per account                   | 100 indexes                                                      |
-| Maximum dimensions per vector         | 1536 dimensions                                                  |
-| Maximum vector ID length              | 64 bytes                                                         |
-| Metadata per vector                   | 10KiB                                                            |
-| Maximum returned results (`topK`)     | 20                                                               |
-| Maximum upsert batch size (per batch) | 1000  (Workers) / 5000 (HTTP API)                                |
-| Maximum index name length             | 63 bytes                                                         |
-| Maximum vectors per index             | 200,000                                                          |
-| Maximum namespaces per index          | 1000 namespaces                                                  |
-| Maximum namespace name length         | 63 bytes                                                         |
\ No newline at end of file
+| Feature                               | Current Limit                    |
+| ------------------------------------- | -------------------------------- |
+| Indexes per account                   | 100 indexes                      |
+| Maximum dimensions per vector         | 1536 dimensions                  |
+| Maximum vector ID length              | 64 bytes                         |
+| Metadata per vector                   | 10KiB                            |
+| Maximum returned results (`topK`)     | 20                               |
+| Maximum upsert batch size (per batch) | 1000 (Workers) / 5000 (HTTP API) |
+| Maximum index name length             | 63 bytes                         |
+| Maximum vectors per index             | 200,000                          |
+| Maximum namespaces per index          | 1000 namespaces                  |
+| Maximum namespace name length         | 63 bytes                         |
diff --git a/src/content/docs/vectorize/reference/client-api.mdx b/src/content/docs/vectorize/reference/client-api.mdx
index 03d664813cd450..f0706c5ed4f40b 100644
--- a/src/content/docs/vectorize/reference/client-api.mdx
+++ b/src/content/docs/vectorize/reference/client-api.mdx
@@ -21,9 +21,9 @@ let vectorsToInsert = [
 let inserted = await env.YOUR_INDEX.insert(vectorsToInsert);
 ```
 
-Inserts vectors into the index. Returns the count of vectors inserted and their IDs.
+Inserts vectors into the index. Vectorize inserts are asynchronous and the insert operation returns a mutation identifier unique for that operation. It typically takes a few seconds for inserted vectors to be available for querying in a Vectorize index.
 
-If vectors with the same vector ID already exist in the index, only the vectors with new IDs will be inserted. The returned `VectorizeVectorMutation` will return a `count` and an `ids` array with IDs of the vectors inserted into the index, and omit IDs that already exist in the index.
+If vectors with the same vector ID already exist in the index, only the vectors with new IDs will be inserted.
 
 If you need to update existing vectors, use the [upsert](#upsert-vectors) operation.
 
@@ -38,7 +38,7 @@ let vectorsToUpsert = [
 let upserted = await env.YOUR_INDEX.upsert(vectorsToUpsert);
 ```
 
-Upserts vectors into an index. Returns the count of vectors upserted and their IDs.
+Upserts vectors into an index. Vectorize upserts are asynchronous and the upsert operation returns a mutation identifier unique for that operation. It typically takes a few seconds for upserted vectors to be available for querying in a Vectorize index.
 
 An upsert operation will insert vectors into the index if vectors with the same ID do not exist, and overwrite vectors with the same ID.
 
@@ -53,18 +53,36 @@ let matches = await env.YOUR_INDEX.query(queryVector);
 
 Query an index with the provided vector, returning the score(s) of the closest vectors based on the configured distance metric.
 
-- Configure the number of returned matches by setting `topK` (default: 3)
+- Configure the number of returned matches by setting `topK` (default: 5)
 - Return vector values by setting `returnValues: true` (default: false)
-- Return vector metadata by setting `returnMetadata: true` (default: false)
+- Return vector metadata by setting `returnMetadata: 'indexed'` or `returnMetadata: 'all'` (default: 'none')
 
 ```ts
 let matches = await env.YOUR_INDEX.query(queryVector, {
 	topK: 5,
 	returnValues: true,
-	returnMetadata: true,
+	returnMetadata: "all",
 });
 ```
 
+#### topK
+
+The `topK` can be configured to specify the number of matches returned by the query operation. Vectorize now supports an upper limit of `100` for the `topK` value. However, for a query operation with `returnValues` set to `true` or `returnMetadata` set to `all`, `topK` would be limited to a maximum value of `20`.
+
+#### returnMetadata
+
+The `returnMetadata` field provides three ways to fetch vector metadata while querying:
+
+1. `none`: Do not fetch metadata.
+2. `indexed`: Fetched metadata only for the indexed metadata fields. There is no latency overhead with this option, but long text fields may be truncated.
+3. `all`: Fetch all metadata associated with a vector. Queries may run slower with this option, and `topK` would be limited to 20.
+
+:::note[`topK` and `returnMetadata` for legacy Vectorize indexes]
+
+For legacy Vectorize (V1) indexes, `topK` is limited to 20, and the `returnMetadata` is a boolean field.
+
+:::
+
 ### Get vectors by ID
 
 ```ts
@@ -81,7 +99,7 @@ let idsToDelete = ["11", "22", "33", "44"];
 const deleted = await env.YOUR_INDEX.deleteByIds(idsToDelete);
 ```
 
-Deletes the vector IDs provided from the current index. Returns a count of the IDs provided and the list of vector IDs.
+Deletes the vector IDs provided from the current index. Vectorize deletes are asynchronous and the delete operation returns a mutation identifier unique for that operation. It typically takes a few seconds for vectors to be removed from the Vectorize index.
 
 ### Retrieve index details
 
diff --git a/src/content/docs/vectorize/reference/metadata-filtering.mdx b/src/content/docs/vectorize/reference/metadata-filtering.mdx
index 4639192e30e17f..7ea25e50166a18 100644
--- a/src/content/docs/vectorize/reference/metadata-filtering.mdx
+++ b/src/content/docs/vectorize/reference/metadata-filtering.mdx
@@ -5,12 +5,15 @@ sidebar:
   order: 6
 ---
 
+import { Render, PackageManagers } from "~/components";
+
 # Metadata Filtering
 
 :::note[Enable metadata filtering]
 
-Vectorize v2 requires to define metadata properties that will support filtering. Please refer to [Vectorize API](/vectorize/reference/client-api/#create-metadata-index) for details.
-[Namespaces](/vectorize/best-practices/insert-vectors/#namespaces) support metadata filtering by default.
+Vectorize requires metadata indexes to be specified before vectors are inserted to support metadata filtering. Please refer to [Vectorize API](/vectorize/reference/client-api/#create-metadata-index) for details.
+
+Vectorize supports [namespace](/vectorize/best-practices/insert-vectors/#namespaces) filtering by default.
 
 :::
 
@@ -62,23 +65,31 @@ Both [namespaces](/vectorize/best-practices/insert-vectors/#namespaces) and meta
 
 ```json
 { "pandas.nice": 42 }
- // looks for { "pandas": { "nice": 42 } }
+
+
+// looks for { "pandas": { "nice": 42 } }
 ```
 
 ## Examples
 
 ### Add metadata
 
-:::note[Using Vectorize v1?]
+<Render file="vectorize-legacy" />
 
-Please use the 'wrangler vectorize --deprecated-v1' flag to create, get, list, delete and insert vectors into legacy Vectorize v1 indexes.
+With the following index definition:
 
-:::
+```sh
+npx wrangler vectorize create tutorial-index --dimensions=32 --metric=cosine
+```
 
-With the following index definition:
+Create metadata indexes:
+
+```sh
+npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
+```
 
 ```sh
-npx wrangler vectorize create tutorial-index --dimensions=3 --metric=cosine
+npx wrangler vectorize create-metadata-index tutorial-index --property-name=streaming_platform --type=string
 ```
 
 Metadata can be added when [inserting or upserting vectors](/vectorize/best-practices/insert-vectors/#examples).
@@ -87,27 +98,27 @@ Metadata can be added when [inserting or upserting vectors](/vectorize/best-prac
 const newMetadataVectors: Array<VectorizeVector> = [
 	{
 		id: "1",
-		values: [32.4, 74.1, 3.2],
+		values: [32.4, 74.1, 3.2, ...],
 		metadata: { url: "/products/sku/13913913", streaming_platform: "netflix" },
 	},
 	{
 		id: "2",
-		values: [15.1, 19.2, 15.8],
+		values: [15.1, 19.2, 15.8, ...],
 		metadata: { url: "/products/sku/10148191", streaming_platform: "hbo" },
 	},
 	{
 		id: "3",
-		values: [0.16, 1.2, 3.8],
+		values: [0.16, 1.2, 3.8, ...],
 		metadata: { url: "/products/sku/97913813", streaming_platform: "amazon" },
 	},
 	{
 		id: "4",
-		values: [75.1, 67.1, 29.9],
+		values: [75.1, 67.1, 29.9, ...],
 		metadata: { url: "/products/sku/418313", streaming_platform: "netflix" },
 	},
 	{
 		id: "5",
-		values: [58.8, 6.7, 3.4],
+		values: [58.8, 6.7, 3.4, ...],
 		metadata: { url: "/products/sku/55519183", streaming_platform: "hbo" },
 	},
 ];
@@ -121,12 +132,11 @@ let upserted = await env.YOUR_INDEX.upsert(newMetadataVectors);
 Use the `query()` method:
 
 ```ts
-let queryVector: Array<number> = [54.8, 5.5, 3.1];
-// Best match is vector id = 5 (score closet to 1)
+let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
 let originalMatches = await env.YOUR_INDEX.query(queryVector, {
 	topK: 3,
 	returnValues: true,
-	returnMetadata: true,
+	returnMetadata: 'all',
 });
 ```
 
@@ -169,13 +179,12 @@ Results without metadata filtering:
 The same `query()` method with a `filter` property supports metadata filtering.
 
 ```ts
-let queryVector: Array<number> = [54.8, 5.5, 3.1];
-// Best match is vector id = 4 with metadata filter
+let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
 let metadataMatches = await env.YOUR_INDEX.query(queryVector, {
 	topK: 3,
 	filter: { streaming_platform: "netflix" },
 	returnValues: true,
-	returnMetadata: true,
+	returnMetadata: 'all',
 });
 ```
 
@@ -208,4 +217,5 @@ Results with metadata filtering:
 
 ## Limitations
 
-- Only newly created indexes on or after 2023-12-06 support metadata filtering. Previously created indexes cannot be migrated to support metadata filtering.
+- As of now, metadata indexes need to be created for Vectorize indexes _before_ vectors can be inserted to support metadata filtering.
+- Only indexes created on or after 2023-12-06 support metadata filtering. Previously created indexes cannot be migrated to support metadata filtering.
diff --git a/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx b/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
new file mode 100644
index 00000000000000..c8f070fc17cdff
--- /dev/null
+++ b/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
@@ -0,0 +1,76 @@
+---
+title: Transition legacy Vectorize indexes
+pcx_content_type: concept
+sidebar:
+  order: 8
+---
+
+Legacy Vectorize (V1) indexes are on a deprecation path as of Aug 15, 2024. Your Vectorize index may be a legacy index if it fulfills any of the follwing crieria:
+
+1. Was created with a Wrangler version lower than `v3.71.0`.
+2. Was created using the "--deprecated-v1" flag enabled.
+3. Was created using the legacy [REST API](</api/operations/vectorize-(-deprecated)-create-vectorize-index>).
+
+This document provides details around any transition steps that may be needed to move away from legacy Vectorize indexes.
+
+## Why should I transition?
+
+Legacy Vectorize (V1) indexes are on a deprecation path. Support for these indexes would be limited and their usage is not recommended for any production workloads.
+
+Additionally, the new Vectorize (V2) indexes can operate at a significantly larger scale (with a capacity for multi-million vectors), and provide faster performance. Please review the [Limits](/vectorize/platform/limits/) page to understand the latest capabilities supported by Vectorize.
+
+## Notable changes
+
+In addition to supporting significantly larger indexes with multi-million vectors, and faster performance, these are some of the changes that need to be considered when transitioning away from legacy Vectorize indexes:
+
+1. The new Vectorize (V2) indexes now support asynchronous mutations. Any vector inserts or deletes, and metadata index creation or deletes may take a few seconds to be reflected.
+
+2. Vectorize (V2) support metadata and namespace filtering for much larger indexes with significantly lower latencies. However, the fields on which metadata filtering can be applied need to be specified before vectors are inserted. Refer to the [metadata index creation](/vectorize/reference/client-api/#create-metadata-index) page for more details.
+
+3. Vectorize (V2) [query operation](/vectorize/reference/client-api/#query-vectors) now supports the ability to search for and return up to 100 most similar vectors.
+
+4. Vectorize (V2) query operations provide a more granular control for querying metadata along with vectors. Refer to the [query operation](/vectorize/reference/client-api/#query-vectors) page for more details.
+
+5. Vectorize (V2) expands the Vectorize capabilities that are available via Wrangler (with Wrangler version > `v3.71.0`).
+
+## Transition
+
+:::note[Automated Migration]
+
+Watch this space for the upcoming capability to migrate legacy (V1) indexes to the new Vectorize (V2) indexes automatically.
+
+:::
+
+1. Wrangler now supports operations on the new version of Vectorize (V2) indexes by default. To use Wangler commands for legacy (V1) indexes, the `--deprecated-v1` flag must be enabled. Please note that this flag is only supported to create, get, list and delete indexes and to insert vectors.
+
+2. Refer to the [REST API](/api/operations/vectorize-create-vectorize-index) page for details on the routes and payload types for the new Vectorize (V2) indexes. For legacy (V1) index operations, refer to [Deprecated REST API](</api/operations/vectorize-(-deprecated)-create-vectorize-index>).
+
+3. To use the new version of Vectorize indexes in Workers, the environment binding must be defined as a `Vectorize` interface.
+
+   ```typescript
+   export interface Env {
+   	// This makes your vector index methods available on env.VECTORIZE.*
+   	// For example, env.VECTORIZE.insert() or query()
+   	VECTORIZE: Vectorize;
+   }
+   ```
+
+   The `Vectorize` interface includes the type changes and the capabilities supported by new Vectorize (V2) indexes.
+
+   For legacy Vectorize (V1) indexes, use the `VectorizeIndex` interface.
+
+   ```typescript
+   export interface Env {
+   	// This makes your vector index methods available on env.VECTORIZE.*
+   	// For example, env.VECTORIZE.insert() or query()
+   	VECTORIZE: VectorizeIndex;
+   }
+   ```
+
+4. With the new Vectorize (V2) version, the `returnMetadata` option for the [query operation](/vectorize/reference/client-api/#query-vectors) now expects either `all`, `indexed` or `none` string values. For legacy Vectorize (V1), the `returnMetadata` option was a boolean field.
+
+5. With the new Vectorize (V2) indexes, all index and vector mutations are asynchronous and return a `mutationId` in the response as a unique identifier for that mutation operation.
+
+   These mutation operations are: [Vector Inserts](/vectorize/reference/client-api/#insert-vectors), [Vector Upserts](/vectorize/reference/client-api/#upsert-vectors), [Vector Deletes](/vectorize/reference/client-api/#delete-vectors-by-id), [Metadata Index Creation](/vectorize/reference/client-api/#create-metadata-index), [Metadata Index Deletion](/vectorize/reference/client-api/#delete-metadata-index).
+
+   To check the identifier and the timestamp of the last mutation processed, use the Vectorize [Info command](/vectorize/reference/client-api/#get-index-info).
diff --git a/src/content/partials/vectorize/vectorize-legacy.mdx b/src/content/partials/vectorize/vectorize-legacy.mdx
new file mode 100644
index 00000000000000..a9628f4e963848
--- /dev/null
+++ b/src/content/partials/vectorize/vectorize-legacy.mdx
@@ -0,0 +1,11 @@
+---
+{}
+---
+
+:::note[Using legacy Vectorize (V1) indexes?]
+
+Please use the `wrangler vectorize --deprecated-v1` flag to create, get, list, delete and insert vectors into legacy Vectorize V1 indexes.
+
+Refer to the [legacy transition](/vectorize/reference/transition-vectorize-legacy) page for more details on transitioning away from legacy indexes.
+
+:::
diff --git a/src/content/partials/vectorize/vectorize-wrangler-version.mdx b/src/content/partials/vectorize/vectorize-wrangler-version.mdx
index 30c18fa550c1b2..23565d255ba3ae 100644
--- a/src/content/partials/vectorize/vectorize-wrangler-version.mdx
+++ b/src/content/partials/vectorize/vectorize-wrangler-version.mdx
@@ -1,12 +1,9 @@
 ---
 {}
-
 ---
 
 :::note[Wrangler version 3.71.0 required]
 
-
-Vectorize v2 requires [wrangler](/workers/wrangler/install-and-update/) version `3.71.0` or later. Ensure you have the latest version of `wrangler` installed, or use `npx wrangler@latest vectorize` to always use the latest version.
-
+Vectorize V2 requires [wrangler](/workers/wrangler/install-and-update/) version `3.71.0` or later. Ensure you have the latest version of `wrangler` installed, or use `npx wrangler@latest vectorize` to always use the latest version.
 
 :::

From 314646d3e83e4e08e8d0f30053a83bebd80abb40 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 12:28:15 +0100
Subject: [PATCH 2/8] Update
 src/content/docs/vectorize/best-practices/query-vectors.mdx

---
 src/content/docs/vectorize/best-practices/query-vectors.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/best-practices/query-vectors.mdx b/src/content/docs/vectorize/best-practices/query-vectors.mdx
index 2a0c6b7284a5cc..2bac5d6b49983f 100644
--- a/src/content/docs/vectorize/best-practices/query-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/query-vectors.mdx
@@ -16,7 +16,8 @@ To pass a vector as a query to an index, use the `query()` method on the index i
 A query vector is either an array of JavaScript numbers, 32-bit floating point or 64-bit floating point numbers: `number[]`, `Float32Array`, or `Float64Array`. Unlike when [inserting vectors](/vectorize/best-practices/insert-vectors/), a query vector does not need an ID or metadata.
 
 ```ts
-let queryVector = [54.8, 5.5, 3.1, ...]; // query vector dimensions should match the Vectorize index dimension being queried
+// query vector dimensions should match the Vectorize index dimension being queried
+let queryVector = [54.8, 5.5, 3.1, ...]; 
 let matches = await env.YOUR_INDEX.query(queryVector);
 ```
 

From 9a9b69ad56828ca3fc724e3c6ffd2d55eab20e5a Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 12:28:30 +0100
Subject: [PATCH 3/8] Update
 src/content/docs/vectorize/best-practices/query-vectors.mdx

---
 src/content/docs/vectorize/best-practices/query-vectors.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/best-practices/query-vectors.mdx b/src/content/docs/vectorize/best-practices/query-vectors.mdx
index 2bac5d6b49983f..d30b51dccab921 100644
--- a/src/content/docs/vectorize/best-practices/query-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/query-vectors.mdx
@@ -41,7 +41,8 @@ This would return a set of matches resembling the following, based on the distan
 You can optionally change the number of results returned and/or whether results should include metadata and values:
 
 ```ts
-let queryVector = [54.8, 5.5, 3.1, ...]; // query vector dimensions should match the Vectorize index dimension being queried
+// query vector dimensions should match the Vectorize index dimension being queried
+let queryVector = [54.8, 5.5, 3.1, ...]; 
 // topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
 let matches = await env.YOUR_INDEX.query(queryVector, {
 	topK: 1,

From 91f43debb2ad9739a64ea5224ddba9e05c303824 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 12:39:55 +0100
Subject: [PATCH 4/8] Update
 src/content/docs/vectorize/reference/metadata-filtering.mdx

---
 src/content/docs/vectorize/reference/metadata-filtering.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/reference/metadata-filtering.mdx b/src/content/docs/vectorize/reference/metadata-filtering.mdx
index 7ea25e50166a18..6cfd0b42b22d56 100644
--- a/src/content/docs/vectorize/reference/metadata-filtering.mdx
+++ b/src/content/docs/vectorize/reference/metadata-filtering.mdx
@@ -11,7 +11,7 @@ import { Render, PackageManagers } from "~/components";
 
 :::note[Enable metadata filtering]
 
-Vectorize requires metadata indexes to be specified before vectors are inserted to support metadata filtering. Please refer to [Vectorize API](/vectorize/reference/client-api/#create-metadata-index) for details.
+Vectorize requires metadata indexes to be specified before vectors are inserted to support metadata filtering. Please refer to [Create metadata indexes](/vectorize/get-started/intro/#4-optional-create-metadata-indexes) for details.
 
 Vectorize supports [namespace](/vectorize/best-practices/insert-vectors/#namespaces) filtering by default.
 

From b517c32f2674aaa732f408e072eab05a3106cb81 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 12:56:25 +0100
Subject: [PATCH 5/8] Update
 src/content/docs/vectorize/best-practices/query-vectors.mdx

---
 src/content/docs/vectorize/best-practices/query-vectors.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/best-practices/query-vectors.mdx b/src/content/docs/vectorize/best-practices/query-vectors.mdx
index d30b51dccab921..b420bcb42501bb 100644
--- a/src/content/docs/vectorize/best-practices/query-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/query-vectors.mdx
@@ -16,7 +16,7 @@ To pass a vector as a query to an index, use the `query()` method on the index i
 A query vector is either an array of JavaScript numbers, 32-bit floating point or 64-bit floating point numbers: `number[]`, `Float32Array`, or `Float64Array`. Unlike when [inserting vectors](/vectorize/best-practices/insert-vectors/), a query vector does not need an ID or metadata.
 
 ```ts
-// query vector dimensions should match the Vectorize index dimension being queried
+// query vector dimensions must match the Vectorize index dimension being queried
 let queryVector = [54.8, 5.5, 3.1, ...]; 
 let matches = await env.YOUR_INDEX.query(queryVector);
 ```

From 34ad6b96506412e4b43c041ed97ea82bfaebfd77 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 12:56:53 +0100
Subject: [PATCH 6/8] Update
 src/content/docs/vectorize/best-practices/query-vectors.mdx

---
 src/content/docs/vectorize/best-practices/query-vectors.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/best-practices/query-vectors.mdx b/src/content/docs/vectorize/best-practices/query-vectors.mdx
index b420bcb42501bb..09defbd59a0556 100644
--- a/src/content/docs/vectorize/best-practices/query-vectors.mdx
+++ b/src/content/docs/vectorize/best-practices/query-vectors.mdx
@@ -41,7 +41,7 @@ This would return a set of matches resembling the following, based on the distan
 You can optionally change the number of results returned and/or whether results should include metadata and values:
 
 ```ts
-// query vector dimensions should match the Vectorize index dimension being queried
+// query vector dimensions must match the Vectorize index dimension being queried
 let queryVector = [54.8, 5.5, 3.1, ...]; 
 // topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
 let matches = await env.YOUR_INDEX.query(queryVector, {

From 60d3633e2f20bccd7f3171265033805ac2db5031 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 13:05:35 +0100
Subject: [PATCH 7/8] Update
 src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx

Co-authored-by: Kody Jackson <kody@cloudflare.com>
---
 .../docs/vectorize/reference/transition-vectorize-legacy.mdx    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx b/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
index c8f070fc17cdff..02a3bcb5f64acc 100644
--- a/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
+++ b/src/content/docs/vectorize/reference/transition-vectorize-legacy.mdx
@@ -9,7 +9,7 @@ Legacy Vectorize (V1) indexes are on a deprecation path as of Aug 15, 2024. Your
 
 1. Was created with a Wrangler version lower than `v3.71.0`.
 2. Was created using the "--deprecated-v1" flag enabled.
-3. Was created using the legacy [REST API](</api/operations/vectorize-(-deprecated)-create-vectorize-index>).
+3. Was created using the legacy [REST API](/api/operations/vectorize-(-deprecated)-create-vectorize-index).
 
 This document provides details around any transition steps that may be needed to move away from legacy Vectorize indexes.
 

From 71fa6fd7dd5c2c415289c53240fe8ae76835bb47 Mon Sep 17 00:00:00 2001
From: Yevgen Safronov <yevgen@cloudflare.com>
Date: Fri, 23 Aug 2024 13:05:43 +0100
Subject: [PATCH 8/8] Update
 src/content/docs/vectorize/best-practices/create-indexes.mdx

Co-authored-by: Kody Jackson <kody@cloudflare.com>
---
 src/content/docs/vectorize/best-practices/create-indexes.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/vectorize/best-practices/create-indexes.mdx b/src/content/docs/vectorize/best-practices/create-indexes.mdx
index f1519ed93d10aa..676098a9018659 100644
--- a/src/content/docs/vectorize/best-practices/create-indexes.mdx
+++ b/src/content/docs/vectorize/best-practices/create-indexes.mdx
@@ -67,7 +67,7 @@ print('Status Code:', resp.status_code)
 print('Response JSON:', resp.json())
 ```
 
-This script should print the response with a status code 201, along with a JSON response body indicating the creation of an index with the provided configuration.
+This script should print the response with a status code `201`, along with a JSON response body indicating the creation of an index with the provided configuration.
 
 ## Dimensions