Clarified the result set (#35574)

Author: Davide Mauri

docs/t-sql/functions/vector-search-transact-sql.md

@@ -1,10 +1,10 @@
 ---
 title: "VECTOR_SEARCH (Transact-SQL)"
-description: "VECTOR_SEARCH search for vectors similar to a given query vectors using an approximate nearest neighbors vector search algorithm."
+description: VECTOR_SEARCH search for vectors similar to a given query vectors using an approximate nearest neighbors vector search algorithm.
 author: yorek
 ms.author: damauri
-ms.reviewer: damauri, mikeray
-ms.date: 08/11/2025
+ms.reviewer: mikeray, randolphwest
+ms.date: 10/14/2025
 ms.service: sql
 ms.subservice: t-sql
 ms.topic: reference
@@ -17,15 +17,15 @@ helpviewer_keywords:
   - "VECTOR_SEARCH function"
   - "vector, search"
 dev_langs:
-  - "TSQL"
+  - TSQL
 monikerRange: "=sql-server-ver17 || =sql-server-linux-ver17"
 ---
 
 # VECTOR_SEARCH (Transact-SQL) (Preview)
 
 [!INCLUDE [sqlserver2025](../../includes/applies-to-version/sqlserver2025.md)]
 
-Search for vectors similar to a given query vectors using an approximate nearest neighbors vector search algorithm. To learn more about how vector indexing and vector search works, and the differences between exact and approximate search, refer to [Vectors in the SQL Database Engine](../../sql-server/ai/vectors.md).
+Search for vectors similar to a given query vectors using an approximate nearest neighbors vector search algorithm. To learn more about how vector indexing and vector search works, and the differences between exact and approximate search, refer to [Vector search and vector indexes in the SQL Database Engine](../../sql-server/ai/vectors.md).
 
 ## Preview feature
 
@@ -78,7 +78,16 @@ The alias is used to reference the result set.
 
 ## Return result set
 
-The returned result set has all the columns from the table specified in TABLE argument, plus the extra `distance` column. The `distance` column contains the distance between the given vector in the COLUMN argument and the vector specified in SIMILAR_TO argument.
+The result set returned by the `VECTOR_SEARCH` function includes:
+
+- All columns from the table specified in the `TABLE` argument.
+- An additional column named `distance`, which represents the distance between the vector in the column specified by the `COLUMN` argument and the vector provided in the `SIMILAR_TO` argument.
+
+The distance column is generated by the `VECTOR_SEARCH` function itself, while all other columns come from the table referenced in the `TABLE` argument.
+
+If you use an alias for the table in the `TABLE` argument, you must use that same alias to reference its columns in the `SELECT` statement. You can't use the alias assigned to `VECTOR_SEARCH` to reference columns from the table specified in `TABLE`. This behavior is easier to understand if you think of the result set as a JSON object that merges the output of `VECTOR_SEARCH` with the table data.
+
+If the table specified in the `TABLE` argument already contains a column named `distance`, the behavior will be similar to a SQL join between two tables that share a column name. In such cases, you must use table aliases to disambiguate the column references—otherwise, an error will be raised.
 
 ## Limitations
 
@@ -91,22 +100,18 @@ The current preview has the following limitations:
 Vector search happens before applying any predicate. Additional predicates are applied only after the most similar vectors are returned. The following sample returns the top 10 rows with embeddings most similar to the query vector `@qv`, then applies the predicate specified in the `WHERE` clause. If none of the 10 rows associated with the vectors returned by the vector search have the `accepted` column equal to 1, the result is empty.
 
 ```sql
-SELECT
-  s.id,
-  s.title,
-  r.distance
-FROM
-  VECTOR_SEARCH(
-    TABLE = dbo.sessions AS s,
-    COLUMN = embedding,
-    SIMILAR_TO = @qv,
-    METRIC = 'cosine',
-    TOP_N = 10
-  ) AS r
-WHERE
-  accepted = 1
-ORDER BY
-  r.distance
+SELECT s.id,
+       s.title,
+       r.distance
+FROM VECTOR_SEARCH(
+         TABLE = dbo.sessions AS s,
+         COLUMN = embedding,
+         SIMILAR_TO = @qv,
+         METRIC = 'cosine',
+         TOP_N = 10
+     ) AS r
+WHERE accepted = 1
+ORDER BY r.distance;
 ```
 
 ### VECTOR_SEARCH can't be used in views
@@ -139,38 +144,34 @@ ORDER BY s.distance
 Same as example 1, but this time the query vectors are taking from another table instead of a variable.
 
 ```sql
-CREATE TABLE #t (
-  id INT,
-  q NVARCHAR(MAX),
-  v VECTOR(1536)
+CREATE TABLE #t
+(
+    id INT,
+    q NVARCHAR (MAX),
+    v VECTOR(1536)
 );
-INSERT INTO
-  #t
-SELECT
-    id, q, ai_generate_embeddings(q USE MODEL Ada2Embeddings)
-FROM
-    (VALUES
+INSERT INTO #t
+SELECT id,
+       q,
+       AI_GENERATE_EMBEDDINGS(q USE MODEL Ada2Embeddings)
+FROM (VALUES
         (1, N'four legged furry animal'),
         (2, N'pink floyd music style')
-    ) S(id, q)
-;
-
-SELECT
-    t.id, s.distance, t.title
-FROM
-    #t AS qv
+) AS S(id, q);
+SELECT t.id,
+       s.distance,
+       t.title
+FROM #t AS qv
 CROSS APPLY
     VECTOR_SEARCH(
-        TABLE = [dbo].[wikipedia_articles_embeddings] as t,
+        TABLE = [dbo].[wikipedia_articles_embeddings] AS t,
         COLUMN = [content_vector],
         SIMILAR_TO = qv.v,
         METRIC = 'cosine',
         TOP_N = 10
-    ) AS s
-WHERE
-  qv.id = 2
-ORDER BY
-  s.distance
+) AS s
+WHERE qv.id = 2
+ORDER BY s.distance;
 ```
 
 ### Example 3
@@ -236,7 +237,7 @@ ORDER BY s.distance, t.title;
 
 ## Related content
 
-- [Overview of vectors in the SQL Database Engine](../../sql-server/ai/vectors.md)
+- [Vector search and vector indexes in the SQL Database Engine](../../sql-server/ai/vectors.md)
 - [Vector data type](../data-types/vector-data-type.md)
 - [CREATE VECTOR INDEX (Transact-SQL)](../statements/create-vector-index-transact-sql.md)
 - [Azure SQL Database Vector Search Samples](https://github.com/Azure-Samples/azure-sql-db-vector-search)