一个实用工具，用于封装Pyarrow二进制列，并以类似文件对象的方式逐行迭代。

这对于处理需要与期望文件类对象的API接口交互的中小型二进制对象非常有用。对于非常大的二进制对象（每个值4-8MB或更大），最好创建一个blob列并使用lance.Dataset.take_blobs()来访问blob数据。

将Lance数据集中的blob表示为类似文件的对象。

close() → None¶

刷新并关闭IO对象。

如果文件已经关闭，此方法将不起作用。

property closed : bool¶

readable() → bool¶

返回对象是否已打开以供读取。

如果为False，read()将抛出OSError异常。

readall() → bytes¶

读取直到文件结束(EOF)，使用多次read()调用。

readinto(b: bytearray) → int¶

seek(offset: int, 何时: int = 0) → int¶

将流位置更改为给定的字节偏移量。

offset

流位置，相对于‘whence’。

whence

相对于当前位置的偏移量。

偏移量是相对于whence所指示的位置进行解释的。 whence的取值包括：

• os.SEEK_SET 或 0 - 流的开始位置（默认值）；偏移量应为零或正数

• os.SEEK_CUR 或 1 – 当前流位置；偏移量可为负值

• os.SEEK_END 或 2 – 流的末尾；偏移量通常为负数

返回新的绝对位置。

seekable() → bool¶

返回对象是否支持随机访问。

如果为False，seek()、tell()和truncate()将引发OSError。 此方法可能需要进行测试seek()。

size() → int¶

返回blob的大小（以字节为单位）。

tell() → int¶

返回当前流的位置。

数据集中的数据统计信息

fields : FieldStatistics¶

数据集中字段的统计信息

数据集中某个字段的统计信息

bytes_on_disk : int¶

（可能经过压缩的）磁盘上用于存储该字段的字节

id : int¶

字段的ID

片段的元数据。

id¶

片段的ID。

Type:

整数

files¶

片段的数据文件。每个数据文件必须具有相同的行数。每个文件存储不同列的子集。

Type:

列表[DataFile]

physical_rows¶

该片段最初的行数。这是删除前数据文件中的行数。

Type:

int

deletion_file¶

删除文件（如果有的话）。

Type:

可选[DeletionFile]

row_id_meta¶

行ID元数据（如果有的话）。

Type:

可选[RowIdMeta]

data_files() → list[DataFile]¶

deletion_file : DeletionFile | None = None¶

files : List[数据文件]¶

static from_json(json_data: str) → FragmentMetadata¶

id : int¶

property num_deletions : int¶

已从此片段中删除的行数。

property num_rows : int¶

删除操作后此片段中的行数。

physical_rows : int¶

row_id_meta : RowIdMeta | None = None¶

to_json() → dict¶

获取这个作为简单的JSON可序列化字典。

Lance数据集采用Lance格式，数据存储在给定的uri位置。

add_columns(转换: dict[str, str] | BatchUDF | ReaderLike | pyarrow.Field | list[pyarrow.Field] | pyarrow.Schema, read_columns: list[str] | None = None, reader_schema: pa.Schema | None = None, batch_size: int | None = None)¶

使用定义的值添加新列。

有几种方式可以指定新列。首先，可以为每个新列提供SQL表达式。其次，可以提供一个UDF（用户定义函数），该函数接收一批现有数据并返回包含新列的新数据批次。这些新列将被追加到数据集中。

你也可以提供一个RecordBatchReader，它将从某个外部源读取新列的值。当新列的值已经暂存到文件中（通常由某个分布式进程完成）时，这通常很有用。

有关编写UDF的更多信息，请参阅lance.add_columns_udf()装饰器。

Parameters:

transforms : dict or AddColumnsUDF or ReaderLike¶

如果这是一个字典，那么键是新列的名称，值则是SQL表达式字符串。这些字符串可以引用数据集中的现有列。 如果这是一个AddColumnsUDF，那么它是一个用户定义函数，接收一批现有数据并返回包含新列的新数据批次。 如果这是pyarrow.Field或pyarrow.Schema，则会以仅元数据操作的方式添加所有具有给定模式的NULL列。

read_columns : list of str, optional¶

UDF将读取的列名。如果为None，则UDF将读取所有列。仅当transforms是UDF时使用此参数。否则，读取的列将从SQL表达式中推断得出。

reader_schema : pa.Schema, optional¶

仅当transforms是ReaderLike对象时有效。这将用于确定读取器的模式。

batch_size : int, optional¶

在应用转换时，每次从源数据集中读取的行数。如果数据集是v1版本，则忽略此参数。

示例

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3]})
>>> dataset = lance.write_dataset(table, "my_dataset")
>>> @lance.batch_udf()
... def double_a(batch):
...     df = batch.to_pandas()
...     return pd.DataFrame({'double_a': 2 * df['a']})
>>> dataset.add_columns(double_a)
>>> dataset.to_table().to_pandas()
   a  double_a
0  1         2
1  2         4
2  3         6
>>> dataset.add_columns({"triple_a": "a * 3"})
>>> dataset.to_table().to_pandas()
   a  double_a  triple_a
0  1         2         3
1  2         4         6
2  3         6         9

另请参阅

LanceDataset.merge

将一组预先计算好的列合并到数据集中。

alter_columns(*修改: Iterable[AlterColumn])¶

修改列名、数据类型和可空性。

重命名的列可以保留其上的任何索引。如果某列具有IVF_PQ索引，即使该列被转换为其他类型，索引仍可保留。但目前其他类型的索引尚不支持类型转换。

列类型可以进行向上转型（例如从int32转为int64）或向下转型（例如从int64转为int32）。但若存在无法用新类型表示的值时，向下转型会失败。通常来说，列可以转型为相同的大类类型：整型转整型、浮点型转浮点型、字符串转字符串。不过字符串、二进制和列表列可以在其大小变体之间进行转型。例如：字符串转大字符串、二进制转大二进制、列表转大列表。

重命名的列可以保留其上的任何索引。但是，如果将该列转换为不同类型，其索引将被删除。

Parameters:

alterations : Iterable[Dict[str, Any]]¶

一个字典序列，每个字典包含以下键：

• ”path”: str

  要修改的列路径。对于顶级列，这是列名。 对于嵌套列，这是点分隔的路径，例如"a.b.c"。

• ”name”: str, optional

  列的新名称。如果未指定，则列名保持不变。

• ”nullable”: bool, optional

  列是否可为空。如果未指定，则列的可空性不变。 只能将非空列改为可空列。目前不能将可空列改为非空列。

• ”data_type”: pyarrow.DataType, optional

  要将列转换到的新数据类型。如果未指定，则列的数据类型保持不变。

示例

>>> import lance
>>> import pyarrow as pa
>>> schema = pa.schema([pa.field('a', pa.int64()),
...                     pa.field('b', pa.string(), nullable=False)])
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example")
>>> dataset.alter_columns({"path": "a", "name": "x"},
...                       {"path": "b", "nullable": True})
>>> dataset.to_table().to_pandas()
   x  b
0  1  a
1  2  b
2  3  c
>>> dataset.alter_columns({"path": "x", "data_type": pa.int32()})
>>> dataset.schema
x: int32
b: string

checkout_version(版本: int | str) → LanceDataset¶

加载指定版本的数据集。

与dataset()构造函数不同，此操作将重用当前缓存。如果数据集已处于指定版本，则此操作无效。

Parameters:

version : int | str,¶

要检出的版本号。可以提供一个版本号（int）或标签（str）。

Return type:

LanceDataset

cleanup_old_versions(older_than: timedelta | None = None, *, delete_unverified: bool = False, error_if_tagged_old_versions: bool = True) → CleanupStats¶

清理数据集的旧版本。

某些数据集变更（如覆盖操作）会遗留未被最新版本引用的数据。这些旧数据会被保留，以便将数据集回滚到之前的版本。

该方法将移除旧版本及其引用的所有数据文件。 一旦清理任务执行完毕，您将无法检出或恢复这些旧版本。

Parameters:

older_than : timedelta, optional¶

仅早于此版本的记录将被删除。如果未指定，默认保留两周内的记录。

delete_unverified : bool, default False¶

事务失败后遗留的文件可能看起来像是正在进行中的操作（例如追加新数据）的一部分，这些文件只有在至少7天后才会被删除。如果delete_unverified为True，则无论文件存在多久都会被删除。

只有在您能确保当前没有其他进程正在处理此数据集时，才应将此设置为True。否则数据集可能会进入损坏状态。

error_if_tagged_old_versions : bool, default True¶

某些版本可能关联了标签。带标签的版本不会被清理，无论它们存在多久。如果该参数设为True（默认值），当任何带标签版本匹配参数时会抛出异常。否则，带标签版本将被静默忽略，仅清理未加标签的版本。

static commit(base_uri: str | Path | LanceDataset, 操作: LanceOperation.BaseOperation | 事务, blobs_op: LanceOperation.BaseOperation | None = None, read_version: int | None = None, commit_lock: CommitLock | None = None, storage_options: dict[str, str] | None = None, enable_v2_manifest_paths: bool | None = None, 分离: bool | None = False, max_retries: int = 20) → LanceDataset¶

创建数据集的新版本

该方法是一个高级方法，允许用户描述对数据文件所做的更改。当使用Lance应用变更时（例如使用LanceDataset或write_dataset()），则不需要此方法。

它当前的目的是允许在分布式环境中进行更改，其中没有单一进程完成所有工作。例如，分布式批量更新或分布式批量修改操作。

一旦完成所有更改，可以调用此方法通过更新数据集清单使更改生效。

警告

这是一个高级API，不提供与其他API相同级别的验证。例如，调用者有责任确保片段对模式有效。

Parameters:

base_uri : str, Path, or LanceDataset¶

数据集的基URI，或数据集对象本身。使用数据集对象可能更高效，因为它可以复用文件元数据缓存。

operation : BaseOperation¶

应用于数据集的操作。这描述了已进行的更改。可用的操作请参见LanceOperation。

read_version : int, optional¶

作为变更基础的数据集版本。 覆盖或恢复操作不需要此版本。

commit_lock : CommitLock, optional¶

自定义提交锁。仅当您的对象存储不支持原子提交时才需要。详情请参阅用户指南。

storage_options : optional, dict¶

针对特定存储连接的额外选项。这用于存储连接参数，如凭证、端点等。

enable_v2_manifest_paths : bool, optional¶

如果为True，且这是一个新数据集，则使用新的V2清单路径。 这些路径能更高效地在对象存储上打开包含多个版本的数据集。如果数据集已存在，此参数将不起作用。要迁移现有数据集，请改用migrate_manifest_paths_v2()方法。默认为False。警告： 启用此选项将使旧版Lance（0.17.0之前版本）无法读取该数据集。

detached : bool, optional¶

如果为True，则该提交不会成为数据集谱系的一部分。它将永远不会显示为最新数据集，未来唯一查看它的方式是通过指定版本号检出。该版本将是一个随机版本号，仅在分离提交中保持唯一。调用方应将其存储在某处，因为未来将无法通过其他方式获取它。

max_retries : int¶

提交数据集时执行的最大重试次数。

Returns:

Lance数据集的新版本。

Return type:

LanceDataset

示例

使用LanceOperation.Overwrite操作创建新数据集：

>>> import lance
>>> import pyarrow as pa
>>> tab1 = pa.table({"a": [1, 2], "b": ["a", "b"]})
>>> tab2 = pa.table({"a": [3, 4], "b": ["c", "d"]})
>>> fragment1 = lance.fragment.LanceFragment.create("example", tab1)
>>> fragment2 = lance.fragment.LanceFragment.create("example", tab2)
>>> fragments = [fragment1, fragment2]
>>> operation = lance.LanceOperation.Overwrite(tab1.schema, fragments)
>>> dataset = lance.LanceDataset.commit("example", operation)
>>> dataset.to_table().to_pandas()
   a  b
0  1  a
1  2  b
2  3  c
3  4  d

static commit_batch(dest: str | Path | LanceDataset, 交易: collections.abc.Sequence[事务], commit_lock: CommitLock | None = None, storage_options: dict[str, str] | None = None, enable_v2_manifest_paths: bool | None = None, 分离: bool | None = False, max_retries: int = 20) → BulkCommitResult¶

使用多个事务创建数据集的新版本。

此方法是一个高级方法，允许用户描述对数据文件所做的更改。当使用Lance应用更改时（例如使用LanceDataset或write_dataset()），则不需要此方法。

Parameters:

dest : str, Path, or LanceDataset¶

数据集的基础URI，或者数据集对象本身。使用数据集对象可能更高效，因为它可以复用文件元数据缓存。

transactions : Iterable[Transaction]¶

要应用于数据集的事务操作。这些操作将被合并为单个事务并应用到数据集中。注意：目前仅支持追加事务，其他类型的事务将在未来版本中支持。

commit_lock : CommitLock, optional¶

自定义提交锁。仅当您的对象存储不支持原子提交时才需要。详情请参阅用户指南。

storage_options : optional, dict¶

针对特定存储连接的额外选项。这用于存储连接参数，如凭证、端点等。

enable_v2_manifest_paths : bool, optional¶

如果为True，且这是一个新数据集，则使用新的V2清单路径。 这些路径能更高效地在对象存储上打开包含多个版本的数据集。如果数据集已存在，此参数将不起作用。要迁移现有数据集，请改用migrate_manifest_paths_v2()方法。默认为False。警告： 启用此选项将使旧版Lance（0.17.0之前版本）无法读取该数据集。

detached : bool, optional¶

如果为True，则该提交不会成为数据集谱系的一部分。它将永远不会显示为最新数据集，未来唯一查看它的方式是通过指定版本号检出。该版本将是一个随机版本号，仅在分离提交中保持唯一。调用方应将其存储在某处，因为未来将无法通过其他方式获取它。

max_retries : int¶

提交数据集时执行的最大重试次数。

Returns:

dataset: LanceDataset

Lance数据集的新版本。

merged: Transaction

应用于数据集的合并事务。

Return type:

包含键的字典

count_rows(filter: 表达式 | str | None = None, **kwargs) → int¶

统计符合扫描器筛选条件的行数。

Parameters:

**kwargs : dict, optional¶

完整参数描述请参见 py:method:scanner 方法。

Returns:

count – 数据集中的总行数。

Return type:

int

create_index(列: str | list[str], index_type: str, name: str | None = None, metric: str = 'L2', replace: bool = False, num_partitions: int | None = None, ivf_centroids: np.ndarray | pa.FixedSizeListArray | pa.FixedShapeTensorArray | None = None, pq_codebook: np.ndarray | pa.FixedSizeListArray | pa.FixedShapeTensorArray | None = None, num_sub_vectors: int | None = None, accelerator: str | 'torch.Device' | None = None, index_cache_size: int | None = None, shuffle_partition_batches: int | None = None, shuffle_partition_concurrency: int | None = None, ivf_centroids_file: str | None = None, precomputed_partition_dataset: str | None = None, storage_options: dict[str, str] | None = None, filter_nan: bool = True, one_pass_ivfpq: bool = False, **kwargs) → LanceDataset¶

在列上创建索引。

实验性API

Parameters:

column : str¶

要建立索引的列。

index_type : str¶

索引的类型。 "IVF_PQ, IVF_HNSW_PQ 和 IVF_HNSW_SQ" 目前支持。

name : str, optional¶

索引名称。如果未提供，将根据列名自动生成。

metric : str¶

距离度量类型，即“L2”（“euclidean”的别名）、“cosine”或“dot”（点积）。默认为“L2”。

replace : bool¶

如果索引已存在，则替换现有索引。

num_partitions : int, optional¶

IVF（倒排文件索引）的分区数量。

ivf_centroids : optional¶

它可以是np.ndarray、 pyarrow.FixedSizeListArray或 pyarrow.FixedShapeTensorArray。 一个num_partitions x dimension维度的现有K均值中心点数组， 用于IVF聚类。如果未提供，将训练一个新的KMeans模型。

pq_codebook : optional,¶

它可以是np.ndarray、pyarrow.FixedSizeListArray， 或pyarrow.FixedShapeTensorArray。 一个num_sub_vectors x (2 ^ nbits * dimensions // num_sub_vectors) 数组，表示PQ码本的K均值中心点。

注意：目前nbits始终为8。 如果未提供，将训练一个新的PQ模型。

num_sub_vectors : int, optional¶

PQ（乘积量化）的子向量数量。

accelerator: str | 'torch.Device' | None = None¶

如果设置，将使用加速器来加快训练过程。 支持的加速器包括："cuda"（英伟达GPU）和"mps"（苹果硅GPU）。 如果未设置，则使用CPU。

index_cache_size : int, optional¶

索引缓存的大小，以条目数表示。默认值为256。

shuffle_partition_batches : int, optional¶

批次数，使用数据集的row group大小，决定每个shuffle分区包含的数量。默认值为10240。

假设row group大小为1024，每个shuffle分区将包含10240 * 1024 = 10,485,760行。减小此值会减少shuffle操作的内存消耗但会增加完成时间，反之亦然。

shuffle_partition_concurrency : int, optional¶

并发处理的shuffle分区数量。默认值为2

减小该值可以减少shuffle操作的内存消耗，但会增加完成时间，反之亦然。

storage_options : optional, dict¶

针对特定存储连接的额外选项。这用于存储连接参数，如凭证、端点等。

filter_nan : bool¶

默认为True。False是不安全的，如果存在任何null/nan值会导致崩溃（否则不会）。禁用用于可空列的空值过滤器。可获得小幅速度提升。

one_pass_ivfpq : bool¶

默认为False。如果启用，索引类型必须为“IVF_PQ”。可减少磁盘IO。

**kwargs¶

传递给索引构建过程的参数。

SQ（标量量化）仅适用于IVF_HNSW_SQ索引类型，这种量化方法用于减少索引的内存占用，它将浮点向量映射为整数向量，每个整数占用num_bits位，目前仅支持8位。

If index_type is “IVF_*”, then the following parameters are required:

num_partitions

If index_type is with “PQ”, then the following parameters are required:

子向量数量

IVF_PQ的可选参数：

• ivf_centroids

  用于IVF聚类的现有K均值中心点。

• num_bits

  PQ(乘积量化)的位数。默认为8。 仅支持4和8。

Optional parameters for IVF_HNSW_*:

max_level

Int，图中最大层级数。

m

Int，图中每个节点的边数。

ef_construction

Int，构建过程中需要检查的节点数量。

示例

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_PQ",
    num_partitions=256,
    num_sub_vectors=16
)

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_HNSW_SQ",
    num_partitions=256,
)

实验性加速器（GPU）支持：

• accelerate: 使用GPU训练IVF分区。

  目前仅支持CUDA(Nvidia)或MPS(Apple)。 需要安装PyTorch。

import lance

dataset = lance.dataset("/tmp/sift.lance")
dataset.create_index(
    "vector",
    "IVF_PQ",
    num_partitions=256,
    num_sub_vectors=16,
    accelerator="cuda"
)

参考文献

• Faiss索引

• IVF 在Video Google: a text retrieval approach to object matching in videos中提出

• 用于最近邻搜索的产品量化

create_scalar_index(列: str, index_type: 'BTREE' | 'BITMAP' | 'LABEL_LIST' | 'INVERTED' | 'FTS' | 'NGRAM', name: str | None = None, *, 替换: bool = True, **kwargs)¶

在列上创建标量索引。

标量索引与向量索引类似，可用于加速扫描。当扫描包含对已索引列的过滤表达式时，标量索引能显著提升查询速度。例如，若my_col列建有标量索引，以下扫描操作将执行得更快：

import lance

dataset = lance.dataset("/tmp/images.lance")
my_table = dataset.scanner(filter="my_col != 7").to_table()

带有预过滤器的向量搜索也可以从标量索引中受益。例如，

import lance

dataset = lance.dataset("/tmp/images.lance")
my_table = dataset.scanner(
    nearest=dict(
       column="vector",
       q=[1, 2, 3, 4],
       k=10,
    )
    filter="my_col != 7",
    prefilter=True
)

目前有5种标量索引类型可供选择。

• BTREE。最常见的类型是BTREE。该索引的灵感来源于btree数据结构，尽管只有btree的前几层会被缓存在内存中。它将在具有大量唯一值且每个值对应行数较少的列上表现良好。

• BITMAP。该索引为列中的每个唯一值存储一个位图。这种索引适用于具有少量唯一值且每个值对应多行数据的列。

• LABEL_LIST. 一种特殊索引，用于对值基数较小的列表列进行索引。例如，包含标签列表的列（如 ["tag1", "tag2", "tag3"]）可以使用 LABEL_LIST 索引。该索引只能加速带有 array_has_any 或 array_has_all 过滤器的查询。

• NGRAM. 一种用于索引字符串列的特殊索引。该索引会为字符串中的每个n元语法创建位图，默认使用三元语法。当前该索引可以加速在过滤器中使用contains函数的查询。

• FTS/INVERTED. 该索引用于文档列。这种索引可以进行全文搜索。例如，一个包含查询字符串"hello world"中任意单词的列。结果将按BM25排序。

请注意，可以使用环境变量LANCE_BYPASS_SPILLING来绕过磁盘溢出。将其设置为true可以避免内存耗尽问题（更多信息请参阅https://github.com/apache/datafusion/issues/10073）。

实验性API

Parameters:

column : str¶

要建立索引的列。必须是布尔型、整型、浮点型或字符串类型的列。

index_type : str¶

索引的类型。可选值为 "BTREE", "BITMAP", "LABEL_LIST", "NGRAM", "FTS" 或 "INVERTED"。

name : str, optional¶

索引名称。如果未提供，将根据列名自动生成。

replace : bool, default True¶

如果索引已存在，则替换现有索引。

with_position : bool, default True

这是针对INVERTED索引的。如果设为True，索引将存储文档中单词的位置信息，以便支持短语查询。这将显著增加索引大小。即使设置为True，也不会影响非短语查询的性能。

base_tokenizer : str, default "simple"

这是针对INVERTED索引的配置。指定使用的基础分词器，可选值包括： * "simple"：根据空白字符和标点符号进行分词。 * "whitespace"：仅根据空白字符进行分词。 * "raw"：不进行分词处理。

language : str, default "English"

这是针对INVERTED索引的。用于词干提取和停用词处理的语言。仅当stem或remove_stop_words为true时使用

max_token_length : Optional[int], default 40

这是针对INVERTED索引的设置。表示最大令牌长度。任何超过此长度的令牌将被移除。

lower_case : bool, default True

这是针对INVERTED索引的。如果设为True，索引会将所有文本转换为小写。

stem : bool, default False

这是针对INVERTED索引的。如果为True，索引将对词干进行提取。

remove_stop_words : bool, default False

这是针对INVERTED索引的。如果为True，该索引将移除停用词。

ascii_folding : bool, default False

这是针对INVERTED索引的。如果设为True，索引会尽可能将非ASCII字符转换为ASCII字符。例如会将带重音符号的字母如"é"转换为"e"。

示例

import lance

dataset = lance.dataset("/tmp/images.lance")
dataset.create_index(
    "category",
    "BTREE",
)

标量索引只能加速使用等值、比较、范围（例如my_col BETWEEN 0 AND 100）和集合成员（例如my_col IN (0, 1, 2)）等基础过滤条件的扫描

当筛选条件包含多个索引列且这些条件通过AND或OR逻辑连接时，可以使用标量索引 (例如 my_col < 0 AND other_col> 100)

如果过滤条件包含未建立索引的列，虽然可以使用标量索引，但根据过滤条件的结构，可能无法实际使用。例如，若列not_indexed没有标量索引，那么过滤条件my_col = 0 OR not_indexed = 1将无法利用my_col上的任何标量索引。

要判断扫描是否使用了标量索引，可以使用explain_plan查看lancedb生成的查询计划。使用标量索引的查询将包含ScalarIndexQuery关系或MaterializeIndex操作符。

property data_storage_version : str¶

该数据集所使用的数据存储格式版本

delete(predicate: str | 表达式)¶

从数据集中删除行。

这会将行标记为已删除，但不会从文件中物理移除它们。这样可以保持现有索引仍然有效。

Parameters:

predicate : str or pa.compute.Expression¶

用于选择要删除行的谓词。可以是SQL字符串或pyarrow表达式。

示例

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example")
>>> dataset.delete("a = 1 or b in ('a', 'b')")
>>> dataset.to_table()
pyarrow.Table
a: int64
b: string
----
a: [[3]]
b: [["c"]]

static drop(base_uri: str | Path, storage_options: dict[str, str] | None = None) → None¶

drop_columns(columns: list[str])¶

从数据集中删除一列或多列

这是一个仅涉及元数据的操作，不会从底层存储中删除实际数据。如需删除数据，您必须随后调用compact_files来重写不包含被删除列的数据，然后调用cleanup_old_versions来移除旧文件。

Parameters:

columns : list of str¶

要删除的列名。这些可以是嵌套列引用（例如“a.b.c”）或顶级列名（例如“a”）。

示例

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example")
>>> dataset.drop_columns(["a"])
>>> dataset.to_table().to_pandas()
   b
0  a
1  b
2  c

drop_index(name: str)¶

从数据集中删除索引

注意：索引是通过"索引名称"删除的。这与字段名称不同。如果在创建索引时未指定名称，则会自动生成一个名称。您可以使用list_indices方法来获取索引的名称。

get_fragment(fragment_id: int) → LanceFragment | None¶

根据片段ID获取对应的片段。

get_fragments(filter: Expression | None = None) → list[LanceFragment]¶

从数据集中获取所有片段。

注意：过滤器功能暂不支持。

property has_index¶

head(num_rows, **kwargs)¶

加载数据集的前N行。

Parameters:

num_rows : int¶

要加载的行数。

**kwargs : dict, optional¶

完整参数描述请参见scanner()方法。

Returns:

表格

Return type:

表格

index_statistics(index_name: str) → dict[str, Any]¶

insert(数据: ReaderLike, *, mode='append', **kwargs)¶

将数据插入数据集。

Parameters:

data_obj : Reader-like

要写入的数据。可接受的类型包括： - Pandas DataFrame、Pyarrow Table、Dataset、Scanner 或 RecordBatchReader - Huggingface 数据集

mode : str, default 'append'¶

写入数据时使用的模式。可选选项有：

create - 创建新数据集（如果uri已存在则会报错）。 overwrite - 创建新的快照版本 append - 创建新版本，该版本是输入数据与最新版本的合并（如果uri不存在则会报错）

**kwargs : dict, optional¶

传递给write_dataset()的其他关键字参数。

join(right_dataset, keys, right_keys=None, join_type='left outer', left_suffix=None, right_suffix=None, coalesce_keys=True, use_threads=True)¶

未实现（仅覆盖pyarrow数据集以防止段错误）

property lance_schema : LanceSchema¶

该数据集的LanceSchema

property latest_version : int¶

返回数据集的最新版本。

list_indices() → list[索引]¶

property max_field_id : int¶

清单中的max_field_id

merge(data_obj: ReaderLike, left_on: str, right_on: str | None = None, schema=None)¶

将另一个数据集合并到当前数据集中。

执行左连接操作，其中数据集作为左表，data_obj作为右表。存在于数据集但不在左表中的行将被填充为null值，除非Lance不支持某些类型的null值，这种情况下会抛出错误。

Parameters:

data_obj : Reader-like¶

要合并的数据。可接受的类型包括： - Pandas DataFrame、Pyarrow Table、Dataset、Scanner、 Iterator[RecordBatch] 或 RecordBatchReader

left_on : str¶

数据集中用于连接的列名。

right_on : str or None¶

数据对象中用于连接的列名。如果为None，则默认为left_on。

示例

>>> import lance
>>> import pyarrow as pa
>>> df = pa.table({'x': [1, 2, 3], 'y': ['a', 'b', 'c']})
>>> dataset = lance.write_dataset(df, "dataset")
>>> dataset.to_table().to_pandas()
   x  y
0  1  a
1  2  b
2  3  c
>>> new_df = pa.table({'x': [1, 2, 3], 'z': ['d', 'e', 'f']})
>>> dataset.merge(new_df, 'x')
>>> dataset.to_table().to_pandas()
   x  y  z
0  1  a  d
1  2  b  e
2  3  c  f

另请参阅

LanceDataset.add_columns

通过逐批计算添加新列。

merge_insert(开启: str | Iterable[str]) → MergeInsertBuilder¶

返回一个构建器，可用于创建“合并插入”操作

该操作可以在单个事务中添加行、更新行和删除行。这是一个非常通用的工具，可用于实现诸如“如果不存在则插入”、“更新或插入（即upsert）”等行为，甚至可以用新数据替换部分现有数据（例如替换所有月份为“一月”的数据）。

合并插入操作通过使用连接将源表中的新数据与目标表中的现有数据相结合。记录分为三类。

"匹配"记录是指同时存在于源表和目标表中的记录。"未匹配"记录仅存在于源表中（例如这些是新数据）。"源未匹配"记录仅存在于目标表中（这是旧数据）。

此方法返回的构建器可用于自定义每种数据类别应执行的操作。

请注意，此操作会导致数据重新排序。这是因为更新的行会从数据集中删除，然后以新值重新插入到末尾。由于内部使用了哈希连接操作，新插入行的顺序可能会随机波动。

Parameters:

on : Union[str, Iterable[str]]¶

要连接的列（或多列）。这是源表和目标表中记录匹配的方式。通常这是某种键或ID列。

示例

使用when_matched_update_all()和when_not_matched_insert_all()来执行"upsert"操作。这将更新数据集中已存在的行，并插入不存在的行。

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [2, 1, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example")
>>> new_table = pa.table({"a": [2, 3, 4], "b": ["x", "y", "z"]})
>>> # Perform a "upsert" operation
>>> dataset.merge_insert("a")     \
...             .when_matched_update_all()     \
...             .when_not_matched_insert_all() \
...             .execute(new_table)
{'num_inserted_rows': 1, 'num_updated_rows': 2, 'num_deleted_rows': 0}
>>> dataset.to_table().sort_by("a").to_pandas()
   a  b
0  1  b
1  2  x
2  3  y
3  4  z

使用when_not_matched_insert_all()执行"不存在则插入"操作。这只会插入数据集中尚不存在的行。

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example2")
>>> new_table = pa.table({"a": [2, 3, 4], "b": ["x", "y", "z"]})
>>> # Perform an "insert if not exists" operation
>>> dataset.merge_insert("a")     \
...             .when_not_matched_insert_all() \
...             .execute(new_table)
{'num_inserted_rows': 1, 'num_updated_rows': 0, 'num_deleted_rows': 0}
>>> dataset.to_table().sort_by("a").to_pandas()
   a  b
0  1  a
1  2  b
2  3  c
3  4  z

您不需要提供所有列。如果只想更新部分列，可以省略不想更新的列。被省略的列在更新时会保留现有值，如果是插入操作则会设为null。

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"], \
...                   "c": ["x", "y", "z"]})
>>> dataset = lance.write_dataset(table, "example3")
>>> new_table = pa.table({"a": [2, 3, 4], "b": ["x", "y", "z"]})
>>> # Perform an "upsert" operation, only updating column "a"
>>> dataset.merge_insert("a")     \
...             .when_matched_update_all()     \
...             .when_not_matched_insert_all() \
...             .execute(new_table)
{'num_inserted_rows': 1, 'num_updated_rows': 2, 'num_deleted_rows': 0}
>>> dataset.to_table().sort_by("a").to_pandas()
   a  b     c
0  1  a     x
1  2  x     y
2  3  y     z
3  4  z  None

migrate_manifest_paths_v2()¶

将清单路径迁移到新格式。

这将更新清单以使用新的v2格式路径。

该函数具有幂等性，可以多次运行而不会改变对象存储的状态。

警告：当其他并发操作正在进行时，不应运行此操作。 并且该操作应在完成后再恢复其他操作。

property optimize : DatasetOptimizer¶

property partition_expression¶

未实现（仅覆盖pyarrow数据集以防止段错误）

prewarm_index(name: str)¶

预热索引

这将把整个索引加载到内存中。这有助于避免索引查询时的冷启动问题。如果索引无法放入索引缓存中，则会导致I/O浪费。

Parameters:

name : str¶

需要预热的索引名称。

replace_field_metadata(field_name: str, new_metadata: dict[str, str])¶

替换模式中某个字段的元数据

Parameters:

field_name : str¶

要替换元数据的字段名称

new_metadata : dict¶

要设置的新元数据

replace_schema(schema: 模式/架构)¶

未实现（仅覆盖pyarrow数据集以防止段错误）

参见 :py:method:`replace_schema_metadata` 或 :py:method:`replace_field_metadata`

replace_schema_metadata(new_metadata: dict[str, str])¶

替换数据集的结构元数据

Parameters:

new_metadata : dict¶

要设置的新元数据

restore()¶

将当前检出的版本恢复为数据集的最新版本。

这将创建一个新的提交。

sample(num_rows: int, columns: list[str] | dict[str, str] | None = None, randomize_order: bool = True, **kwargs) → 表格¶

随机选取数据样本

Parameters:

num_rows : int¶

要检索的行数

columns : list of str, or dict of str to str default None¶

要获取的列名列表。 或者列名到SQL表达式的字典。 如果为None或未指定，则获取所有列。

**kwargs : dict, optional¶

完整参数描述请参见scanner()方法。

Returns:

表格

Return type:

表格

scanner(columns: list[str] | dict[str, str] | None = None, filter: 表达式 | str | None = None, limit: int | None = None, offset: int | None = None, nearest: dict | None = None, batch_size: int | None = None, batch_readahead: int | None = None, fragment_readahead: int | None = None, scan_in_order: bool | None = None, 片段: Iterable[LanceFragment] | None = None, full_text_query: str | dict | FullTextQuery | None = None, *, prefilter: bool | None = None, with_row_id: bool | None = None, with_row_address: bool | None = None, use_stats: bool | None = None, fast_search: bool | None = None, io_buffer_size: int | None = None, late_materialization: bool | list[str] | None = None, use_scalar_index: bool | None = None, include_deleted_rows: bool | None = None, scan_stats_callback: Callable[[ScanStatistics], None] | None = None, strict_batch_size: bool | None = None) → LanceScanner¶

返回一个支持各种下推操作的Scanner。

Parameters:

columns : list of str, or dict of str to str default None¶

要获取的列名列表。 或者列名到SQL表达式的字典。 如果为None或未指定，则获取所有列。

filter : pa.compute.Expression or str¶

表达式或字符串，必须是一个有效的SQL where子句。有关有效的SQL表达式，请参阅 Lance filter pushdown 。

limit : int, default None¶

最多获取这么多行。如果为None或未指定，则获取所有行。

offset : int, default None¶

从这一行开始获取。如果未指定则为0。

nearest : dict, default None¶

获取与K个最相似向量对应的行。示例：

{
    "column": <embedding col name>,
    "q": <query vector as pa.Float32Array>,
    "k": 10,
    "minimum_nprobes": 20,
    "maximum_nprobes": 50,
    "refine_factor": 1
}

batch_size : int, default None¶

返回批次的目标大小。在某些情况下，批次大小可能达到此值的两倍（但绝不会超过）。而在其他情况下，批次大小可能小于此值。

io_buffer_size : int, default None¶

IO缓冲区的大小。有关更多信息，请参阅ScannerBuilder.io_buffer_size。

batch_readahead : int, optional¶

预读取的批次数量。

fragment_readahead : int, optional¶

预读取的片段数量。

scan_in_order : bool, default True¶

是否按顺序读取片段和批次。如果为false，吞吐量可能会更高，但批次将无序返回，内存使用可能会增加。

fragments : iterable of LanceFragment, default None¶

如果指定，则仅扫描这些片段。如果scan_in_order为True，那么片段将按照给定的顺序进行扫描。

prefilter : bool, default False¶

如果为True，则在运行向量查询之前应用过滤器。 这将生成更准确的结果，但查询成本可能更高。 通常在过滤器具有高选择性时效果良好。

如果为False，则在运行向量查询之后应用过滤器。 这样性能会更好，但如果最接近查询的行不匹配过滤器， 结果可能会少于请求的行数（或为空）。 通常在过滤器选择性不高时效果良好。

use_scalar_index : bool, default True¶

Lance会自动使用标量索引来优化查询。在某些极端情况下，这可能会使查询性能变差，此时可以通过该参数禁用标量索引。

late_materialization : bool or List[str], default None¶

允许自定义控制延迟物化。延迟物化会在过滤操作后通过take操作获取非查询列，这在结果较少或列数据量非常大时非常有用。

当结果较多或列数据非常窄时，早期物化可能更优。

如果设为True，则所有列都采用延迟物化； 如果设为False，则所有列都采用早期物化； 如果是字符串列表，则只有列表中的列会延迟物化。

默认采用启发式算法，假设过滤器会筛选出约0.1%的行。如果您的过滤器选择性更强（例如按id查找），可能需要设为True；如果过滤器选择性较弱（例如匹配20%的行），可能需要设为False。

full_text_query : str or dict, optional¶

要搜索的查询字符串，结果将按BM25算法排序。 例如"hello world"会匹配包含"hello"或"world"的文档。 或者使用包含以下键的字典：

• columns: list[str]

  要搜索的列， 目前columns列表中仅支持单个列。

• query: str

  要搜索的查询字符串。

fast_search : bool, default False¶

如果为True，则搜索将仅在索引数据上执行，这样可以缩短搜索时间。

scan_stats_callback : Callable[[ScanStatistics], None], default None¶

一个回调函数，在扫描完成后将调用该函数并传入扫描统计信息。回调函数引发的错误将被记录但不会重新抛出。

include_deleted_rows : bool, default False¶

如果为True，则已被删除但仍存在于片段中的行将被返回。这些行的_rowid列将被设为null。所有其他列将反映磁盘上存储的值，可能不为null。

注意：如果是搜索操作或take操作（包括标量索引扫描），则无法返回已删除的行。

注意

目前，如果同时指定了filter和nearest，那么：

1. nearest 会优先执行。

2. 结果会在之后进行过滤。

为了调试近似最近邻(ANN)结果，您可以选择即使存在索引也不使用它，只需指定use_index=False。例如，以下代码将始终返回精确的KNN结果：

dataset.to_table(nearest={
    "column": "vector",
    "k": 10,
    "q": <query vector>,
    "use_index": False
}

property schema : 模式/架构¶

该数据集的pyarrow模式

session() → _Session¶

返回数据集会话，该会话保存了数据集的状态。

property stats : LanceStats¶

实验性API

property tags : 标签¶

数据集标签管理。

与Git类似，标签是一种向数据集特定版本添加元数据的方式。

警告

带标签的版本不受cleanup_old_versions()清理过程的影响。

要删除已标记的版本，您必须首先delete()关联的标记。

示例

ds = lance.open("dataset.lance")
ds.tags.create("v2-prod-20250203", 10)

tags = ds.tags.list()

take(索引: list[int] | 数组, columns: list[str] | dict[str, str] | None = None) → 表格¶

按索引选择数据行。

Parameters:

indices : Array or array-like¶

数据集中要选择的行索引。

columns : list of str, or dict of str to str default None¶

要获取的列名列表。 或者列名到SQL表达式的字典。 如果为None或未指定，则获取所有列。

Returns:

表格

Return type:

pyarrow.Table

take_blobs(blob_column: str, ids: list[int] | 数组 | None = None, 地址: list[int] | 数组 | None = None, 索引: list[int] | 数组 | None = None) → list[BlobFile]¶

按行ID选择二进制大对象。

无需在处理前将大型二进制blob数据加载到内存中，该API允许您将二进制blob数据作为常规的Python类文件对象打开。更多详情请参阅lance.BlobFile。

必须且只能指定ids、addresses或indices中的一个参数。 :param blob_column: 要选择的blob列名称。 :type blob_column: str :param ids: 数据集中要选择的行ID。 :type ids: Integer Array或类似数组 :param addresses: 数据集中要选择行的(不稳定)内存地址。 :type addresses: Integer Array或类似数组 :param indices: 数据集中行的偏移量/索引。 :type indices: Integer Array或类似数组

Returns:

blob_files

Return type:

列表[BlobFile]

to_batches(columns: list[str] | dict[str, str] | None = None, filter: 表达式 | str | None = None, limit: int | None = None, offset: int | None = None, nearest: dict | None = None, batch_size: int | None = None, batch_readahead: int | None = None, fragment_readahead: int | None = None, scan_in_order: bool | None = None, *, prefilter: bool | None = None, with_row_id: bool | None = None, with_row_address: bool | None = None, use_stats: bool | None = None, full_text_query: str | dict | None = None, io_buffer_size: int | None = None, late_materialization: bool | list[str] | None = None, use_scalar_index: bool | None = None, strict_batch_size: bool | None = None, **kwargs) → Iterator[RecordBatch]¶

将数据集读取为物化的记录批次。

Parameters:

**kwargs : dict, optional¶

scanner()的参数。

Returns:

record_batches

Return type:

RecordBatch的迭代器

to_table(columns: list[str] | dict[str, str] | None = None, filter: 表达式 | str | None = None, limit: int | None = None, offset: int | None = None, nearest: dict | None = None, batch_size: int | None = None, batch_readahead: int | None = None, fragment_readahead: int | None = None, scan_in_order: bool | None = None, *, prefilter: bool | None = None, with_row_id: bool | None = None, with_row_address: bool | None = None, use_stats: bool | None = None, fast_search: bool | None = None, full_text_query: str | dict | FullTextQuery | None = None, io_buffer_size: int | None = None, late_materialization: bool | list[str] | None = None, use_scalar_index: bool | None = None, include_deleted_rows: bool | None = None) → 表格¶

将数据作为pyarrow.Table读入内存

Parameters:

columns : list of str, or dict of str to str default None¶

要获取的列名列表。 或者列名到SQL表达式的字典。 如果为None或未指定，则获取所有列。

filter : pa.compute.Expression or str¶

表达式或字符串，必须是一个有效的SQL where子句。有关有效的SQL表达式，请参阅 Lance filter pushdown 。

limit : int, default None¶

最多获取这么多行。如果为None或未指定，则获取所有行。

offset : int, default None¶

从这一行开始获取。如果未指定则为0。

nearest : dict, default None¶

获取与K个最相似向量对应的行。示例：

{
    "column": <embedding col name>,
    "q": <query vector as pa.Float32Array>,
    "k": 10,
    "metric": "cosine",
    "minimum_nprobes": 20,
    "maximum_nprobes": 50,
    "refine_factor": 1
}

batch_size : int, optional¶

每次读取的行数。

io_buffer_size : int, default None¶

IO缓冲区的大小。有关更多信息，请参阅ScannerBuilder.io_buffer_size。

batch_readahead : int, optional¶

预读取的批次数量。

fragment_readahead : int, optional¶

预读取的片段数量。

scan_in_order : bool, optional, default True¶

是否按顺序读取片段和批次。如果为false，吞吐量可能会更高，但批次将无序返回，内存使用可能会增加。

prefilter : bool, optional, default False¶

在向量搜索之前运行过滤器。

late_materialization : bool or List[str], default None¶

允许自定义控制延迟物化。更多信息请参阅 ScannerBuilder.late_materialization。

use_scalar_index : bool, default True¶

允许自定义控制标量索引的使用。更多信息请参见 ScannerBuilder.use_scalar_index。

with_row_id : bool, optional, default False¶

返回行ID。

with_row_address : bool, optional, default False¶

返回行地址

use_stats : bool, optional, default True¶

在过滤过程中使用统计下推。

fast_search : bool, optional, default False¶

full_text_query : str or dict, optional¶

用于搜索的查询字符串，结果将按BM25算法排序。 例如："hello world"会匹配包含"hello"或"world"的文档。 或者使用包含以下键的字典：

• columns: list[str]

  要搜索的列， 目前仅支持在列列表中指定单个列。

• query: str

  要搜索的查询字符串。

include_deleted_rows : bool, optional, default False¶

如果为True，则已被删除但仍存在于片段中的行将被返回。这些行的_rowid列将被设为null。所有其他列将反映磁盘上存储的值，可能不为null。

注意：如果是搜索操作或take操作（包括标量索引扫描），则无法返回已删除的行。

笔记

如果同时指定了filter和nearest，那么：

1. nearest 会优先执行。

2. 除非将pre-filter设置为True，否则结果会在之后进行过滤。

update(更新: dict[str, str], where: str | None = None) → UpdateResult¶

更新符合where条件的行的列值。

Parameters:

updates : dict of str to str¶

列名到SQL表达式的映射关系。

where : str, optional¶

一个SQL谓词，指示应更新哪些行。

Returns:

updates – 包含更新行数的字典。

Return type:

字典

示例

>>> import lance
>>> import pyarrow as pa
>>> table = pa.table({"a": [1, 2, 3], "b": ["a", "b", "c"]})
>>> dataset = lance.write_dataset(table, "example")
>>> update_stats = dataset.update(dict(a = 'a + 2'), where="b != 'a'")
>>> update_stats["num_updated_rows"] = 2
>>> dataset.to_table().to_pandas()
   a  b
0  1  a
1  4  b
2  5  c

property uri : str¶

数据的位置

validate()¶

验证数据集。

此操作会检查数据集的完整性，如果数据集已损坏则会抛出异常。

property version : int¶

返回当前检出的数据集版本

versions()¶

返回此数据集中的所有版本。