CREATE TABLE¶

使用 SQL DDL 语句创建新的 Lance 表。

基本表创建¶

创建一个简单表

CREATE TABLE users (
    id BIGINT NOT NULL,
    name STRING,
    email STRING,
    created_at TIMESTAMP
);

使用复杂数据类型创建表

CREATE TABLE events (
    event_id BIGINT NOT NULL,
    user_id BIGINT,
    event_type STRING,
    tags ARRAY<STRING>,
    metadata STRUCT<
        source: STRING,
        version: INT,
        processed_at: TIMESTAMP
    >,
    occurred_at TIMESTAMP
);

向量列¶

Lance 支持用于 AI 工作负载的向量（嵌入）列。这些列在内部存储为 Arrow FixedSizeList[n]，其中 n 是向量维度。由于 Spark SQL 没有原生固定大小的数组类型，您必须使用 ARRAY<FLOAT> 或 ARRAY<DOUBLE> 并结合表属性来指定固定维度。Lance-Spark 连接器将在写入操作期间自动将它们转换为适当的 Arrow FixedSizeList 格式。

支持的类型¶

元素类型：FLOAT (float32)，DOUBLE (float64)
要求:
向量必须不可为空
列中的所有向量必须具有相同的维度
维度通过表属性指定

创建向量列¶

要创建包含向量列的表，请使用表属性模式 <column_name>.arrow.fixed-size-list.size，并将维度作为值

CREATE TABLE embeddings_table (
    id INT NOT NULL,
    text STRING,
    embeddings ARRAY<FLOAT> NOT NULL
) USING lance
TBLPROPERTIES (
    'embeddings.arrow.fixed-size-list.size' = '128'
);

创建具有不同维度的多个向量列的表

CREATE TABLE multi_vector_table (
    id INT NOT NULL,
    title STRING,
    text_embeddings ARRAY<FLOAT> NOT NULL,
    image_embeddings ARRAY<DOUBLE> NOT NULL
) USING lance
TBLPROPERTIES (
    'text_embeddings.arrow.fixed-size-list.size' = '384',
    'image_embeddings.arrow.fixed-size-list.size' = '512'
);

使用向量表¶

创建后，您可以使用 SQL 插入数据

-- Insert vector data (example with small vectors for clarity)
INSERT INTO embeddings_table VALUES
    (1, 'first text', array(0.1, 0.2, 0.3, ...)), -- 128 float values
    (2, 'second text', array(0.4, 0.5, 0.6, ...));

查询向量表

-- Select vectors
SELECT id, text FROM embeddings_table WHERE id = 1;

-- Count rows
SELECT COUNT(*) FROM embeddings_table;

注意：读取向量列时，它们会自动转换为 Spark 的 ARRAY<FLOAT> 或 ARRAY<DOUBLE> 类型，以兼容 Spark 操作。

向量索引¶

创建并填充向量列后，您可以使用 Lance Python API 创建向量索引以进行相似性搜索

import lance

# Open the dataset
ds = lance.dataset("/path/to/embeddings_table.lance")

# Create a vector index on the embeddings column
ds.create_index(
    "embeddings",
    index_type="IVF_PQ",
)

# Perform similarity search
import numpy as np
query_vector = np.random.rand(128).astype(np.float32)
results = ds.to_table(
    nearest={"column": "embeddings", "q": query_vector, "k": 10}
).to_pandas()