Skip to content

Commit 8bf9a24

Browse files
authored
add vector-dims/norm/inner-product and rename vector-distance-function -> vector-distance (#2533)
* add vector-dims/norm/inner-product and rename vector-distance-function -> vector-distance * fix rediect link
1 parent a080142 commit 8bf9a24

File tree

14 files changed

+312
-33
lines changed

14 files changed

+312
-33
lines changed

docs/en/guides/51-ai-functions/02-built-in-functions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Databend provides built-in AI functions powered by Azure OpenAI Service for seam
1818
|----------|-------------|-----------|
1919
| [ai_text_completion](/sql/sql-functions/ai-functions/ai-text-completion) | Generates text based on prompts | • Content generation<br/>• Question answering<br/>• Summarization |
2020
| [ai_embedding_vector](/sql/sql-functions/ai-functions/ai-embedding-vector) | Converts text to vector representations | • Semantic search<br/>• Document similarity<br/>• Content recommendation |
21-
| [cosine_distance](/sql/sql-functions/vector-distance-functions/vector-cosine-distance) | Calculates similarity between vectors | • Finding similar documents<br/>• Ranking search results |
21+
| [cosine_distance](/sql/sql-functions/vector-functions/vector-cosine-distance) | Calculates similarity between vectors | • Finding similar documents<br/>• Ranking search results |
2222

2323
## Vector Storage in Databend
2424

docs/en/sql-reference/00-sql-reference/10-data-types/vector.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ Where:
4343

4444
| Function | Description | Use Case |
4545
|----------|-------------|----------|
46-
| **[cosine_distance](/sql/sql-functions/vector-distance-functions/vector-cosine-distance)** | Calculates cosine distance between vectors | Semantic similarity, text embeddings |
47-
| **[l1_distance](/sql/sql-functions/vector-distance-functions/vector-l1-distance)** | Calculates L1 distance (Manhattan distance) | Feature comparison, sparse data |
48-
| **[l2_distance](/sql/sql-functions/vector-distance-functions/vector-l2-distance)** | Calculates L2 distance (Euclidean distance) | Geometric similarity, image features |
46+
| **[cosine_distance](/sql/sql-functions/vector-functions/vector-cosine-distance)** | Calculates cosine distance between vectors | Semantic similarity, text embeddings |
47+
| **[l1_distance](/sql/sql-functions/vector-functions/vector-l1-distance)** | Calculates L1 distance (Manhattan distance) | Feature comparison, sparse data |
48+
| **[l2_distance](/sql/sql-functions/vector-functions/vector-l2-distance)** | Calculates L2 distance (Euclidean distance) | Geometric similarity, image features |
4949

5050
## Basic Usage
5151

docs/en/sql-reference/20-sql-functions/11-vector-distance-functions/_category_.json

Lines changed: 0 additions & 4 deletions
This file was deleted.

docs/en/sql-reference/20-sql-functions/11-vector-distance-functions/index.md

Lines changed: 0 additions & 22 deletions
This file was deleted.
Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: 'INNER_PRODUCT'
3+
---
4+
5+
import FunctionDescription from '@site/src/components/FunctionDescription';
6+
7+
<FunctionDescription description="Introduced or updated: v1.2.780"/>
8+
9+
Calculates the inner product (dot product) of two vectors, which measures the similarity and projection between vectors.
10+
11+
## Syntax
12+
13+
```sql
14+
INNER_PRODUCT(vector1, vector2)
15+
```
16+
17+
## Arguments
18+
19+
- `vector1`: First vector (VECTOR Data Type)
20+
- `vector2`: Second vector (VECTOR Data Type)
21+
22+
## Returns
23+
24+
Returns a FLOAT value representing the inner product of the two vectors.
25+
26+
## Description
27+
28+
The inner product (also known as dot product) calculates the sum of the products of corresponding elements in two vectors. The function:
29+
30+
1. Verifies that both input vectors have the same length
31+
2. Multiplies corresponding elements from each vector
32+
3. Sums all the products to produce a single scalar value
33+
34+
The mathematical formula implemented is:
35+
36+
```
37+
inner_product(v1, v2) = Σ(v1ᵢ * v2ᵢ)
38+
```
39+
40+
Where v1ᵢ and v2ᵢ are the elements of the input vectors.
41+
42+
The inner product is fundamental in:
43+
- Measuring vector similarity (higher values indicate more similar directions)
44+
- Computing projections of one vector onto another
45+
- Machine learning algorithms (neural networks, SVM, etc.)
46+
- Physics calculations involving work and energy
47+
48+
:::info
49+
This function performs vector computations within Databend and does not rely on external APIs.
50+
:::
51+
52+
## Examples
53+
54+
### Basic Usage
55+
56+
```sql
57+
SELECT INNER_PRODUCT([1,2,3]::VECTOR(3), [4,5,6]::VECTOR(3)) AS inner_product;
58+
```
59+
60+
Result:
61+
```
62+
┌───────────────┐
63+
│ inner_product │
64+
├───────────────┤
65+
│ 32.0 │
66+
└───────────────┘
67+
```
68+
69+
### Working with Table Data
70+
71+
Create a table with vector data:
72+
73+
```sql
74+
CREATE TABLE vector_examples (
75+
id INT,
76+
vector_a VECTOR(3),
77+
vector_b VECTOR(3)
78+
);
79+
80+
INSERT INTO vector_examples VALUES
81+
(1, [1.0, 2.0, 3.0], [4.0, 5.0, 6.0]),
82+
(2, [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]),
83+
(3, [2.0, 3.0, 1.0], [1.0, 2.0, 3.0]);
84+
```
85+
86+
Calculate inner products:
87+
88+
```sql
89+
SELECT
90+
id,
91+
vector_a,
92+
vector_b,
93+
INNER_PRODUCT(vector_a, vector_b) AS inner_product
94+
FROM vector_examples;
95+
```
96+
97+
Result:
98+
```
99+
┌────┬───────────────┬───────────────┬───────────────┐
100+
│ id │ vector_a │ vector_b │ inner_product │
101+
├────┼───────────────┼───────────────┼───────────────┤
102+
│ 1 │ [1.0,2.0,3.0] │ [4.0,5.0,6.0] │ 32.0 │
103+
│ 2 │ [1.0,0.0,0.0] │ [0.0,1.0,0.0] │ 0.0 │
104+
│ 3 │ [2.0,3.0,1.0] │ [1.0,2.0,3.0] │ 11.0 │
105+
└────┴───────────────┴───────────────┴───────────────┘
106+
```
107+
108+
### Vector Similarity Analysis
109+
110+
```sql
111+
-- Calculate inner products to measure vector similarity
112+
SELECT
113+
INNER_PRODUCT([1,0,0]::VECTOR(3), [1,0,0]::VECTOR(3)) AS same_direction,
114+
INNER_PRODUCT([1,0,0]::VECTOR(3), [0,1,0]::VECTOR(3)) AS orthogonal,
115+
INNER_PRODUCT([1,0,0]::VECTOR(3), [-1,0,0]::VECTOR(3)) AS opposite;
116+
```
117+
118+
Result:
119+
```
120+
┌────────────────┬─────────────┬──────────┐
121+
│ same_direction │ orthogonal │ opposite │
122+
├────────────────┼─────────────┼──────────┤
123+
│ 1.0 │ 0.0 │ -1.0 │
124+
└────────────────┴─────────────┴──────────┘
125+
```
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: 'VECTOR_DIMS'
3+
---
4+
5+
import FunctionDescription from '@site/src/components/FunctionDescription';
6+
7+
<FunctionDescription description="Introduced or updated: v1.2.780"/>
8+
9+
Returns the dimensionality (number of elements) of a vector.
10+
11+
## Syntax
12+
13+
```sql
14+
VECTOR_DIMS(vector)
15+
```
16+
17+
## Arguments
18+
19+
- `vector`: Input vector (VECTOR Data Type)
20+
21+
## Returns
22+
23+
Returns a INT value representing the number of dimensions (elements) in the vector.
24+
25+
## Description
26+
27+
The `VECTOR_DIMS` function returns the dimensionality of a vector, which is the number of elements it contains. This function is useful for:
28+
29+
- Validating vector dimensions before performing operations
30+
- Dynamic vector processing where dimension information is needed
31+
- Debugging and data exploration with vector data
32+
- Ensuring compatibility between vectors in calculations
33+
34+
:::info
35+
This function performs vector computations within Databend and does not rely on external APIs.
36+
:::
37+
38+
## Examples
39+
40+
```sql
41+
SELECT
42+
VECTOR_DIMS([1,2]::VECTOR(2)) AS dims_2d,
43+
VECTOR_DIMS([1,2,3]::VECTOR(3)) AS dims_3d,
44+
VECTOR_DIMS([1,2,3,4,5]::VECTOR(5)) AS dims_5d;
45+
```
46+
47+
Result:
48+
```
49+
┌─────────┬─────────┬─────────┐
50+
│ dims_2d │ dims_3d │ dims_5d │
51+
├─────────┼─────────┼─────────┤
52+
│ 2 │ 3 │ 5 │
53+
└─────────┴─────────┴─────────┘
54+
```
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: 'VECTOR_NORM'
3+
---
4+
5+
import FunctionDescription from '@site/src/components/FunctionDescription';
6+
7+
<FunctionDescription description="Introduced or updated: v1.2.780"/>
8+
9+
Calculates the L2 norm (Euclidean norm) of a vector, which represents the length or magnitude of the vector.
10+
11+
## Syntax
12+
13+
```sql
14+
VECTOR_NORM(vector)
15+
```
16+
17+
## Arguments
18+
19+
- `vector`: Input vector (VECTOR Data Type)
20+
21+
## Returns
22+
23+
Returns a FLOAT value representing the L2 norm (magnitude) of the vector.
24+
25+
## Description
26+
27+
The `VECTOR_NORM` function calculates the L2 norm (also known as Euclidean norm) of a vector, which represents its length or magnitude in Euclidean space. The function:
28+
29+
1. Squares each element of the vector
30+
2. Sums all the squared values
31+
3. Returns the square root of the sum
32+
33+
The mathematical formula implemented is:
34+
35+
```
36+
vector_norm(v) = √(Σ(vᵢ²))
37+
```
38+
39+
Where vᵢ are the elements of the input vector.
40+
41+
The vector norm is fundamental in:
42+
- Normalizing vectors to unit length
43+
- Measuring vector magnitude in machine learning
44+
- Computing distances and similarities
45+
- Feature scaling and preprocessing
46+
- Physics calculations involving magnitude
47+
48+
:::info
49+
This function performs vector computations within Databend and does not rely on external APIs.
50+
:::
51+
52+
## Examples
53+
54+
```sql
55+
-- Calculate vector magnitude (length)
56+
SELECT
57+
VECTOR_NORM([3,4]::VECTOR(2)) AS norm_2d,
58+
VECTOR_NORM([1,2,3]::VECTOR(3)) AS norm_3d,
59+
VECTOR_NORM([0,0,0]::VECTOR(3)) AS zero_vector;
60+
```
61+
62+
Result:
63+
```
64+
┌─────────┬───────────┬─────────────┐
65+
│ norm_2d │ norm_3d │ zero_vector │
66+
├─────────┼───────────┼─────────────┤
67+
│ 5.0 │ 3.7416575 │ 0.0 │
68+
└─────────┴───────────┴─────────────┘
69+
```

0 commit comments

Comments
 (0)