PS-11232 [Docs] Add DISTANCE() function for VECTOR data type 9.7

docs/distance-function.md

@@ -0,0 +1,133 @@
+# DISTANCE() Function
+
+The `DISTANCE()` function calculates the distance between two `VECTOR` values. Use this function to compare vectors for similarity search and other vector-based operations.
+
+A vector is an ordered list of numeric values, such as `[1, 2, 3]`. The distance between two vectors is a numeric value that indicates how different the vectors are.
+
+A distance metric defines how the function calculates this value. Different metrics compare properties such as vector values, direction, or magnitude. In general, a smaller distance indicates greater similarity.
+
+`VECTOR_DISTANCE()` is a synonym for `DISTANCE()` and provides compatibility with MySQL 9.x syntax. Both functions accept the same arguments and return the same result.
+
+## Syntax
+
+```sql
+DISTANCE(vector_a, vector_b, metric)
+VECTOR_DISTANCE(vector_a, vector_b, metric)
+```
+
+Both functions require exactly three arguments.
+
+## Arguments
+
+`DISTANCE()` accepts the following arguments:
+
+* `vector_a` and `vector_b` specify the vectors to compare. Both arguments must be `VECTOR` values or binary strings that represent float vectors. Other data types cause an error. The vectors must have the same number of dimensions. A dimension mismatch causes an error.
+* `metric` specifies the distance metric. Use a constant string or hex literal that resolves to a supported metric. Metric names are case-insensitive. You cannot use a column reference or a computed expression, such as `CONCAT()`, for this argument.
+
+For a binary-string vector, the byte length must be a multiple of 4 because each vector element is a 4-byte single-precision floating-point value. An invalid byte length causes an error.
+
+The `metric` argument cannot be `NULL`. An unsupported metric name causes an error.
+
+## Supported distance metrics
+
+The following distance metrics are supported:
+
+| Metric              | Description                                                                                                                                                                                                                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EUCLIDEAN`         | Measures the straight-line distance between two vectors (L2 distance). The result is non-negative. A value of `0` means the vectors are identical. Lower values indicate greater similarity.                                                                                                                        |
+| `EUCLIDEAN_SQUARED` | Calculates the square of the Euclidean distance without the square root calculation. Use this metric when you need to rank vectors by distance but do not need the actual Euclidean distance. The result is non-negative. A value of `0` means the vectors are identical. Lower values indicate greater similarity. |
+| `COSINE`            | Measures the difference in direction between two vectors rather than their magnitude. For real-valued vectors, the result ranges from `0` to `2`. A value of `0` indicates the same direction, while `2` indicates opposite directions.                                                                             |
+| `DOT`               | Calculates the negative inner product (dot product). The dot product multiplies corresponding elements from the two vectors and adds the results. Lower returned values indicate greater similarity.                                                                                                                |
+| `MANHATTAN`         | Adds the absolute differences between corresponding vector elements (L1 distance). The result is non-negative. A value of `0` means the vectors are identical. Lower values indicate greater similarity.                                                                                                            |
+
+## Return value
+
+`DISTANCE()` returns a `DOUBLE` value that represents the result of the selected distance metric. `DOUBLE` is a floating-point numeric data type that can represent fractional values, for example, `5.196152`.
+
+If either input vector is `NULL`, `DISTANCE()` returns `NULL`.
+
+With the `COSINE` metric, `DISTANCE()` returns `NULL` if either vector has a zero L2 norm (magnitude), such as `[0, 0, 0]`. Cosine distance is undefined for a zero vector.
+
+The result is nullable regardless of whether the input columns allow `NULL`. When you use `DISTANCE()` with `CREATE TABLE ... SELECT`, MySQL creates the result column with the `DOUBLE` data type.
+
+## Examples
+
+### Calculate the distance between two vectors
+
+`TO_VECTOR()` converts the string representation of a vector to a `VECTOR` value.
+
+The following example calculates the Euclidean distance between two vectors:
+
+```sql
+SELECT DISTANCE(
+    TO_VECTOR('[1, 2, 3]'),
+    TO_VECTOR('[4, 5, 6]'),
+    'EUCLIDEAN'
+) AS distance;
+```
+
+The result is a `DOUBLE` value:
+
+??? example "Expected output"
+
+````
+```text
++-------------------+
+| distance          |
++-------------------+
+| 5.196152422706632 |
++-------------------+
+```
+````
+
+### Use another distance metric
+
+Specify a different metric in the third argument to change how `DISTANCE()` compares the vectors.
+
+The following example calculates the cosine distance:
+
+```sql
+SELECT DISTANCE(
+    TO_VECTOR('[1, 2, 3]'),
+    TO_VECTOR('[4, 5, 6]'),
+    'COSINE'
+) AS distance;
+```
+
+### Find similar vectors
+
+Assume that the `documents` table contains an `embedding` column defined as `VECTOR(3)`.
+
+Use `DISTANCE()` in an `ORDER BY` clause to rank stored vectors by their distance from a query vector. Sorting by distance in ascending order places the closest vectors first.
+
+The following query uses cosine distance to return the five closest vectors:
+
+```sql
+SELECT id,
+       DISTANCE(
+           embedding,
+           TO_VECTOR('[0.1, 0.2, 0.3]'),
+           'COSINE'
+       ) AS distance
+FROM documents
+ORDER BY distance
+LIMIT 5;
+```
+
+`VECTOR_DISTANCE()` produces the same result:
+
+```sql
+SELECT id,
+       VECTOR_DISTANCE(
+           embedding,
+           TO_VECTOR('[0.1, 0.2, 0.3]'),
+           'COSINE'
+       ) AS distance
+FROM documents
+ORDER BY distance
+LIMIT 5;
+```
+
+## See also
+
+* [The VECTOR Type](vector.md)

docs/vector.md

@@ -0,0 +1,72 @@
+# The VECTOR Type
+
+The `VECTOR` data type stores an ordered list of numeric values, called a vector, in a table column. For example, `[0.1, 0.2, 0.3]` represents a vector with three values.
+
+Vectors can represent numerical features, such as embeddings used for similarity search and machine learning. Each element in a `VECTOR` value uses a single-precision floating-point number.
+
+## Syntax
+
+```sql
+VECTOR(N)
+```
+
+`N` specifies the number of elements, or dimensions, in the vector. All values stored in the column must have the same number of dimensions.
+
+For example, the following statement creates an `embedding` column that stores three-dimensional vectors:
+
+```sql
+CREATE TABLE documents (
+    id INT PRIMARY KEY,
+    title VARCHAR(255),
+    embedding VECTOR(3)
+);
+```
+
+A `VECTOR(3)` value contains exactly three elements, such as `[0.1, 0.2, 0.3]`. A vector with two or four elements does not match the column dimension.
+
+## Store vector values
+
+Use `TO_VECTOR()` to convert the string representation of a vector to a `VECTOR` value.
+
+The following statement inserts a three-dimensional vector into the `embedding` column:
+
+```sql
+INSERT INTO documents (id, title, embedding)
+VALUES (
+    1,
+    'Example document',
+    TO_VECTOR('[0.1, 0.2, 0.3]')
+);
+```
+
+The number of elements passed to `TO_VECTOR()` must match the dimension of the `VECTOR` column.
+
+## Retrieve vector values
+
+Use a `SELECT` statement to retrieve vector values:
+
+```sql
+SELECT id, embedding
+FROM documents;
+```
+
+## Compare vectors
+
+Vector applications often compare vectors to determine how similar they are. The result of a comparison is a numeric distance between the vectors.
+
+Use `DISTANCE()` to calculate this distance with a supported distance metric. For example:
+
+```sql
+SELECT DISTANCE(
+    embedding,
+    TO_VECTOR('[0.1, 0.2, 0.3]'),
+    'COSINE'
+) AS distance
+FROM documents;
+```
+
+Different distance metrics compare vectors in different ways. For details about the supported metrics, arguments, and return values, see [DISTANCE() Function](distance-function.md).
+
+## See also
+
+- [DISTANCE() Function](distance-function.md)

mkdocs-base.yml

@@ -311,6 +311,9 @@ nav:
     - Advanced SQL features:
       - data-types-basic.md
       - functions.md
+      - Vector:
+        - vector.md
+        - distance-function.md
       - sql-conventions.md
       - sql-errors.md
       - sql-syntax.md
@@ -440,4 +443,3 @@ nav:
     - copyright-and-licensing-information.md
     - glossary.md
     - ai-docs.md
-# - Version Selector: "../"