库 API

本页面文档记录了 arcticdb.version_store.library 模块。此模块是给定 Arctic 实例内公开读/写功能的主要接口。

核心功能通过 arcticdb.version_store.library.Library 实例公开。有关如何创建这些实例的说明，请参阅 Arctic API 部分。此模块中公开的其他类型不太重要，用作 arcticdb.version_store.library.Library 实例方法签名的一部分。

arcticdb.version_store.library.Library

给定 Arctic 实例内公开读/写功能的主要接口。

Arctic 库包含命名符号，符号是 Arctic 内数据存储的原子单元。符号包含的数据在大多数情况下类似于 DataFrame，并且经过版本控制，以便可以跟踪和回滚所有修改操作。

此类的实例提供了多种用于写入、修改和删除符号的基本操作，还提供了管理库快照的方法。有关快照的更多信息，请参阅 snapshot 方法。

Arctic 库支持对多个符号进行并发写入和读取，以及对单个符号进行并发读取。但是，不支持对单个符号进行并发写入，除非基本操作明确声明支持单个符号的并发写入。

方法	描述
admin_tools	在此库上进行操作的管理实用程序。
append	将给定数据追加到现有的存储数据。追加操作始终沿着索引进行。将创建新版本
append_batch	以批量方式向多个符号追加数据。这比连续调用多次 append 更高效，因为一些常数时间的操作可以只执行一次，而不是对 append_payloads 中的每个元素都执行一次。
compact_symbol_list	将符号列表缓存压缩到存储中的单个键
defragment_symbol_data	通过合并按行切分的段来压缩碎片化的段 (https://docs.arcticdb.cn/technical/on_disk_storage/#data-layer)。
delete	从库中删除符号的所有版本，除非指定了 version，在这种情况下只删除这些版本。
delete_data_in_range	删除给定日期范围内的数据，创建 symbol 的新版本。
delete_snapshot	删除命名快照。如果给定快照是对底层数据的最后引用，此操作可能需要时间，因为底层数据也将被删除。
delete_staged_data	删除暂存数据。
enterprise_options	在此库上设置的企业库选项。有关非企业选项，另请参阅 options。
finalize_staged_data	最终确定暂存数据，使其可供读取。所有暂存段必须有序且不重叠。
get_description	返回 symbol 的描述性数据。
get_description_batch	返回 symbols 列表中符号的描述性数据。
get_staged_symbols	返回所有具有暂存但未最终确定数据的符号。
has_symbol	此库是否包含给定符号。
head	读取命名符号数据的前 n 行。如果 n 为负数，则返回除最后 n 行之外的所有行。
is_symbol_fragmented	检查压缩可以减少的段数是否大于或等于
list_snapshots	列出库中的快照。
list_symbols	返回此库中的符号。
list_versions	获取此库中的版本，按传入参数过滤。
options	在此库上设置的库选项。另请参阅 enterprise_options。
prune_previous_versions	从数据库中删除给定符号的所有（非快照）版本，但最新版本除外。
read	读取命名符号的数据。返回一个 VersionedItem 对象，其中包含数据和元数据元素（如传入
read_batch	读取多个符号。
read_batch_and_join	批量读取多个符号，然后使用 query_builder 中的第一个子句将它们连接在一起。
read_metadata	返回为符号保存的元数据。此方法比 read 快，因为它只加载元数据，不加载数据本身。
read_metadata_batch	读取多个符号的元数据。
reload_symbol_list	强制重新加载符号列表缓存。
snapshot	创建库中数据的命名快照。
sort_and_finalize_staged_data	对所有暂存数据进行排序和合并，使其可供读取。这与 finalize_staged_data 的区别在于它可以
stage	将暂存数据块写入存储，在对符号调用 finalize_staged_data 之前不可见。
tail	读取命名符号数据的最后 n 行。如果 n 为负数，则返回除前 n 行之外的所有行。
update	用 data 的内容覆盖现有的符号数据。data 中第一个索引条目和最后一个索引条目之间的整个范围将被 data 的内容完全替换，如果需要则添加额外的索引条目。
update_batch	并行对符号列表执行更新操作。所有约束都适用于此调用。
write	将 data 写入指定的 symbol。如果 symbol 已存在，则将创建新版本来引用新写入的数据。
write_batch	批量写入多个符号。
write_metadata	将指定符号名称下的元数据写入此库。数据将保持不变。
write_metadata_batch	以批量方式向多个符号写入元数据。这比连续调用多次 write_metadata 更高效
write_pickle	请参阅 write。此方法与 write 的不同之处仅在于 data 可以是通过 pickle 库序列化的任何类型。
write_pickle_batch	批量写入多个符号，如果需要则对其数据进行 pickle 序列化。

属性	描述
name	此库的名称。

name 属性

name

此库的名称。

admin_tools

admin_tools()

在此库上进行操作的管理实用程序。

append

append(
    symbol: str,
    data: NormalizableType,
    metadata: Any = None,
    prune_previous_versions: bool = False,
    validate_index: bool = True,
) -> Optional[VersionedItem]

将给定数据追加到现有的存储数据。追加操作始终沿着索引进行。将创建新版本来引用新追加的数据。追加操作只接受满足条件的数据：第一行的索引大于或等于现有数据中最后一行的索引。

只有在库配置为支持动态模式时，才能将包含不同列集的数据追加到现有数据中。

如果在不存在的符号上调用 append，它将创建该符号。这在设置新符号时很方便，但请注意 - 它不能用于创建现有符号的新版本。在这种情况下请使用 write。

请注意，append 不支持对单个符号进行多个并发写入。

参数	描述
symbol	符号名称。 类型： str
data	要写入的数据。 类型： NormalizableType
metadata	要与新符号版本一起持久化的可选元数据。请注意，元数据不会以任何方式与存储在先前版本中的元数据合并。 类型： Any 默认值： None
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
validate_index	如果为 True，则验证 data 的索引是否支持日期范围搜索和更新操作。这会测试数据是否按升序排序，使用 Pandas DataFrame.index.is_monotonic_increasing。 类型： bool 默认值： True

返回	描述
VersionedItem	包含存储中写入符号的元数据和版本号的结构。

抛出	描述
UnsortedDataException	如果数据未排序，并且 validate_index 设置为 True 时。

示例

>>> df = pd.DataFrame(
...    {'column': [1,2,3]},
...    index=pd.date_range(start='1/1/2018', end='1/03/2018')
... )
>>> df
            column
2018-01-01       1
2018-01-02       2
2018-01-03       3
>>> lib.write("symbol", df)
>>> to_append_df = pd.DataFrame(
...    {'column': [4,5,6]},
...    index=pd.date_range(start='1/4/2018', end='1/06/2018')
... )
>>> to_append_df
            column
2018-01-04       4
2018-01-05       5
2018-01-06       6
>>> lib.append("symbol", to_append_df)
>>> lib.read("symbol").data
            column
2018-01-01       1
2018-01-02       2
2018-01-03       3
2018-01-04       4
2018-01-05       5
2018-01-06       6

append_batch

append_batch(
    append_payloads: List[WritePayload],
    prune_previous_versions: bool = False,
    validate_index=True,
) -> List[Union[VersionedItem, DataError]]

以批量方式向多个符号追加数据。这比连续调用多次 append 更高效，因为一些常数时间的操作可以只执行一次，而不是对 append_payloads 中的每个元素都执行一次。请注意，这不是一个原子操作 - 有可能一个符号完全写入并可读后，另一个符号才开始写入。

参数	描述
append_payloads	符号及其对应的数据。append_payloads 中不得有重复的符号。 类型： `List[WritePayload]`
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
validate_index	验证批处理中的每个条目都有一个支持日期范围搜索和更新操作的索引。这会测试数据是否按升序排序，使用 Pandas DataFrame.index.is_monotonic_increasing。 默认值： True

返回	描述
List[Union[VersionedItem, DataError]]	版本化项目列表。第 i 个条目对应于 append_payloads 的第 i 个元素。每个结果对应于一个包含存储中受影响符号的元数据和版本号的结构。如果发生键错误或任何其他内部异常，则返回一个 DataError 对象，其中包含 symbol、error_code、error_category 和 exception_string 属性。

抛出	描述
ArcticDuplicateSymbolsInBatchException	当负载中出现重复符号时。
ArcticUnsupportedDataTypeException	如果在任何负载中出现不是 NormalizableType 的数据时。

compact_symbol_list

compact_symbol_list() -> None

将符号列表缓存压缩到存储中的单个键

返回	描述
压缩前的符号列表键数量

抛出	描述
PermissionException	库已在只读模式下打开
InternalException	无法获取压缩符号列表所需的存储锁

defragment_symbol_data

defragment_symbol_data(
    symbol: str,
    segment_size: Optional[int] = None,
    prune_previous_versions: bool = False,
) -> VersionedItem

通过合并按行切分的段来压缩碎片化的段 (https://docs.arcticdb.cn/technical/on_disk_storage/#data-layer)。此方法调用 is_symbol_fragmented 来确定是否继续进行碎片整理操作。

注意 - 请注意，此方法目前的一个主要限制是，在此方法创建的新版本中，数据上存在的任何列切片都将被删除。因此，如果受影响的符号列数超过 127 列（默认值），则在使用 columns 参数选择该符号的单个列时，其性能可能会在碎片整理后的版本中受到负面影响。如果您的符号列数少于 127 列，则此注意事项不适用。有关更多信息，请参阅此处的 columns_per_segment

https://docs.arcticdb.cn/api/arcticdb/arcticdb.LibraryOptions

参数	描述
symbol	符号名称。 类型： str
segment_size	压缩后每个段的最大行数目标。如果未提供此参数，将使用库选项 - "segment_row_size"。请注意，压缩后每个段的行数可能会超过目标。这是为了在压缩后实现最少的段数。有关进一步说明，请参阅下面的示例。 类型： Optional[int] 默认值： None
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False

返回	描述
VersionedItem	包含存储中碎片整理后的符号的元数据和版本号的结构。

抛出	描述
1002 ErrorCategory.INTERNAL:E_ASSERTION_FAILURE	如果 is_symbol_fragmented 返回 false。
2001 ErrorCategory.NORMALIZATION:E_UNIMPLEMENTED_INPUT_TYPE	如果库选项 - "bucketize_dynamic" 为 ON

示例

>>> lib.write("symbol", pd.DataFrame({"A": [0]}, index=[pd.Timestamp(0)]))
>>> lib.append("symbol", pd.DataFrame({"A": [1, 2]}, index=[pd.Timestamp(1), pd.Timestamp(2)]))
>>> lib.append("symbol", pd.DataFrame({"A": [3]}, index=[pd.Timestamp(3)]))
>>> lib_tool = lib._dev_tools.library_tool()
>>> lib_tool.read_index(sym)
                    start_index                     end_index  version_id stream_id          creation_ts          content_hash  index_type  key_type  start_col  end_col  start_row  end_row
1970-01-01 00:00:00.000000000 1970-01-01 00:00:00.000000001          20    b'sym'  1678974096622685727   6872717287607530038          84         2          1        2          0        1
1970-01-01 00:00:00.000000001 1970-01-01 00:00:00.000000003          21    b'sym'  1678974096931527858  12345256156783683504          84         2          1        2          1        3
1970-01-01 00:00:00.000000003 1970-01-01 00:00:00.000000004          22    b'sym'  1678974096970045987   7952936283266921920          84         2          1        2          3        4
>>> lib.version_store.defragment_symbol_data("symbol", 2)
>>> lib_tool.read_index(sym)  # Returns two segments rather than three as a result of the defragmentation operation
                    start_index                     end_index  version_id stream_id          creation_ts         content_hash  index_type  key_type  start_col  end_col  start_row  end_row
1970-01-01 00:00:00.000000000 1970-01-01 00:00:00.000000003          23    b'sym'  1678974097067271451  5576804837479525884          84         2          1        2          0        3
1970-01-01 00:00:00.000000003 1970-01-01 00:00:00.000000004          23    b'sym'  1678974097067427062  7952936283266921920          84         2          1        2          3        4

注意

配置映射设置 - SymbolDataCompact.SegmentCount 将在将来被库设置取代。此 API 也将允许覆盖该设置。

delete

delete(
    symbol: str,
    versions: Optional[Union[int, Iterable[int]]] = None,
)

从库中删除符号的所有版本，除非指定了 version，在这种情况下只删除这些版本。

如果快照仍然引用该版本，这可能不会实际删除底层数据。有关更多详细信息，请参阅 snapshot。

请注意，这可能需要从底层存储中删除数据，这可能会很慢。

此方法不删除任何暂存数据，请使用 delete_staged_data 进行删除。

如果不存在名为 symbol 的符号，则此操作为空操作。特别是，在这种情况下此方法不会引发异常。

参数	描述
symbol	要删除的符号。 类型： str
versions	要删除的符号版本。如果为 None，则将删除所有版本。 类型： Optional[Union[int, Iterable[int]]] 默认值： None

delete_data_in_range

delete_data_in_range(
    symbol: str,
    date_range: Tuple[
        Optional[Timestamp], Optional[Timestamp]
    ],
    prune_previous_versions: bool = False,
)

删除给定日期范围内的数据，创建 symbol 的新版本。

现有的符号版本必须是时间序列索引的。

参数	描述
symbol	符号名称。 类型： str
date_range	要删除数据的日期范围。将元组的任何部分留空为 None 会使该部分的范围保持开放。 类型： Tuple[Optional[Timestamp], Optional[Timestamp]]
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False

示例

>>> df = pd.DataFrame({"column": [5, 6, 7, 8]}, index=pd.date_range(start="1/1/2018", end="1/4/2018"))
>>> lib.write("symbol", df)
>>> lib.delete_data_in_range("symbol", date_range=(datetime.datetime(2018, 1, 1), datetime.datetime(2018, 1, 2)))
>>> lib["symbol"].version
1
>>> lib["symbol"].data
                column
2018-01-03       7
2018-01-04       8

delete_snapshot

delete_snapshot(snapshot_name: str) -> None

删除命名快照。如果给定快照是对底层符号的最后引用，此操作可能需要时间，因为底层数据也将被删除。

参数	描述
snapshot_name	要删除的快照名称。 类型： str

抛出	描述
Exception	如果命名快照不存在。

delete_staged_data

delete_staged_data(symbol: str)

删除暂存数据。

参数	描述
symbol	要删除暂存数据的符号。 类型： `str`

另请参阅

write 关于 staged 参数的文档更详细地解释了暂存数据的概念。

enterprise_options

enterprise_options() -> EnterpriseLibraryOptions

在此库上设置的企业库选项。有关非企业选项，另请参阅 options。

finalize_staged_data

finalize_staged_data(
    symbol: str,
    mode: Optional[
        Union[StagedDataFinalizeMethod, str]
    ] = WRITE,
    prune_previous_versions: bool = False,
    metadata: Any = None,
    validate_index=True,
    delete_staged_data_on_failure: bool = False,
) -> VersionedItem

最终确定暂存数据，使其可供读取。所有暂存段必须有序且不重叠。finalize_staged_data 比 sort_and_finalize_staged_data 更省时。

如果 mode 是 StagedDataFinalizeMethod.APPEND 或 append，则新段第一行的索引必须等于或大于现有数据中最后一行的索引。

如果使用 Static Schema，则所有暂存块必须具有匹配的模式（相同的列名、相同的 dtype、相同的列顺序），并且如果模式是 StagedDataFinalizeMethod.APPEND，则必须与现有数据匹配。有关模式选项的更多信息，请参阅 arcticdb.LibraryOptions.dynamic_schema 的文档。

如果符号不存在，StagedDataFinalizeMethod.APPEND 和 StagedDataFinalizeMethod.WRITE 都会创建它。

如果在符号没有暂存数据的情况下调用 finalize_staged_data，将抛出 UserInputException。使用 get_staged_symbols 检查符号是否存在暂存段。

如果在任何暂存段的索引中包含 NaT 时调用 finalize_staged_data，将抛出 SortingException。

参数	描述
symbol	要最终确定数据的符号。 类型： `str`
mode	最终确定模式。有效选项为 StagedDataFinalizeMethod.WRITE 或 StagedDataFinalizeMethod.APPEND。Write 收集暂存数据并将其写入新版本。Append 收集暂存数据并将其追加到最新版本。也接受 "write" 和 "append"。 类型： Union[`StagedDataFinalizeMethod`, str] 默认值： StagedDataFinalizeMethod.WRITE
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
metadata	要与符号一起持久化的可选元数据。 类型： Any 默认值： None
validate_index	如果为 True，并且暂存段是时间序列，则将验证此操作后符号的索引是否支持日期范围搜索和更新操作。这要求暂存段的索引之间不重叠，并且在 StagedDataFinalizeMethod.APPEND 的情况下，位于先前版本中最后一个索引值之后。 默认值： True
delete_staged_data_on_failure	确定在执行 finalize_staged_data 函数期间发生异常时如何处理暂存数据。 如果设置为 True，则在发生异常时将删除指定符号的所有暂存数据。 如果设置为 False，则将保留暂存数据，并在后续调用 finalize_staged_data 中使用。 要手动删除暂存数据，请使用 delete_staged_data 函数。 类型： bool 默认值： False

返回	描述
VersionedItem	包含存储中写入符号的元数据和版本号的结构。data 成员将为 None。

抛出	描述
SortingException	如果给定符号的任何两个暂存段的索引重叠 如果给定符号的任何暂存段未排序 当使用 StagedDataFinalizeMethod.APPEND 时，如果新段的第一个索引值不大于或等于现有数据中最后一个索引值。 如果任何暂存段的索引包含 NaT
UserInputException	在调用 finalize_staged_data 时没有暂存段时 如果满足以下所有条件 使用了静态模式。 DataFrame 的宽度超过 LibraryOptions.columns_per_segment 的值。 该符号包含并非由 finalize_staged_data 写入的数据。 最终确定模式为 append
SchemaException	如果使用静态模式且并非所有暂存段都具有匹配的模式。 如果使用静态模式，模式为 StagedDataFinalizeMethod.APPEND 且新段的模式与现有数据的模式不同 如果使用动态模式，并且不同段具有相同的列名但其 dtypes 没有共同类型（例如字符串和任何数字类型） 如果在暂存数据中遇到不同的索引名称，无论模式模式如何

另请参阅

write 关于 staged 参数的文档更详细地解释了暂存数据的概念。

示例

>>> lib.write("sym", pd.DataFrame({"col": [3, 4]}, index=pd.DatetimeIndex([pd.Timestamp(2024, 1, 3), pd.Timestamp(2024, 1, 4)])), staged=True)
>>> lib.write("sym", pd.DataFrame({"col": [1, 2]}, index=pd.DatetimeIndex([pd.Timestamp(2024, 1, 1), pd.Timestamp(2024, 1, 2)])), staged=True)
>>> lib.finalize_staged_data("sym")
>>> lib.read("sym").data
            col
2024-01-01    1
2024-01-02    2
2024-01-03    3
2024-01-04    4

get_description

get_description(
    symbol: str, as_of: Optional[AsOf] = None
) -> SymbolDescription

返回 symbol 的描述性数据。

参数	描述
symbol	符号名称。 类型： str
as_of	请参阅 read 的文档。 类型： AsOf 默认值： None

返回	描述
SymbolDescription	包含描述性数据的命名元组。

另请参阅

SymbolDescription 有关每个字段的文档。

get_description_batch

get_description_batch(
    symbols: List[Union[str, ReadInfoRequest]],
) -> List[Union[SymbolDescription, DataError]]

返回 symbols 列表中符号的描述性数据。

参数	描述
symbols	要读取的符号列表。 类型： List[Union[str, ReadInfoRequest]]

返回	描述
List[Union[SymbolDescription, DataError]]	描述性数据列表，其第 i 个元素对应于 symbols 参数的第 i 个元素。如果指定版本不存在，则返回一个 DataError 对象，其中包含 symbol、version_request_type、version_request_data 属性、error_code、error_category 和 exception_string 属性。如果发生键错误或任何其他内部异常，也会返回相同的 DataError 对象。

另请参阅

SymbolDescription 有关每个字段的文档。

get_staged_symbols

get_staged_symbols() -> List[str]

返回所有具有暂存但未最终确定数据的符号。

返回	描述
List[str]	符号名称。

另请参阅

write 关于 staged 参数的文档更详细地解释了暂存数据的概念。

has_symbol

has_symbol(
    symbol: str, as_of: Optional[AsOf] = None
) -> bool

此库是否包含给定符号。

参数	描述
symbol	项目的符号名称 类型： str
as_of	返回数据在某个时间点 (as_of) 的状态。有关更多文档，请参阅 read。如果省略，则考虑在当前时间点存在于库中的符号。 类型： AsOf 默认值： None

返回	描述
bool	如果符号在库中则为 True，否则为 False。

示例

>>> lib.write("symbol", pd.DataFrame())
>>> lib.has_symbol("symbol")
True
>>> lib.has_symbol("another_symbol")
False

contains 运算符也检查符号目前是否存在于此库中

>>> "symbol" in lib
True
>>> "another_symbol" in lib
False

head

head(
    symbol: str,
    n: int = 5,
    as_of: Optional[AsOf] = None,
    columns: List[str] = None,
    lazy: bool = False,
) -> Union[VersionedItem, LazyDataFrame]

读取命名符号数据的前 n 行。如果 n 为负数，则返回除最后 n 行之外的所有行。

参数	描述
symbol	符号名称。 类型： str
n	如果要选择的行数是非负数，否则是要排除的行数。 类型： int 默认值： 5
as_of	请参阅 read 的文档。 类型： AsOf 默认值： None
columns	请参阅 read 的文档。 类型： List[str] 默认值： None
lazy	请参阅 read 的文档。 类型： bool 默认值： False

返回	描述
Union[VersionedItem, LazyDataFrame]	如果 lazy 为 False，则返回 VersionedItem 对象，其中包含 .data 和 .metadata 元素。如果 lazy 为 True，则返回一个 LazyDataFrame 对象，可以在 collect 之前在其上执行进一步的查询。

is_symbol_fragmented

is_symbol_fragmented(
    symbol: str, segment_size: Optional[int] = None
) -> bool

检查压缩可以减少的段数是否大于或等于配置选项 "SymbolDataCompact.SegmentCount" 指定的值（默认为 100）。

参数	描述
symbol	符号名称。 类型： str
segment_size	压缩后每个段的最大行数目标。如果未提供此参数，将使用库选项中的段最大行大小。 类型： Optional[int] 默认值： None

注意

配置映射设置 - SymbolDataCompact.SegmentCount 将在将来被库设置取代。此 API 也将允许覆盖该设置。

返回	描述
bool

list_snapshots

list_snapshots(
    load_metadata: Optional[bool] = True,
) -> Union[List[str], Dict[str, Any]]

列出库中的快照。

参数	描述
load_metadata	加载快照元数据。可能很慢，因此如果不需要，请选择 false。 类型： `Optional[bool]` 默认值： True

返回	描述
Union[List[str], Dict[str, Any]]	库中的快照。如果 load_metadata 为 False，则返回快照名称列表；否则返回一个字典，其中键是快照名称，值是与该快照关联的元数据。

list_symbols

list_symbols(
    snapshot_name: Optional[str] = None,
    regex: Optional[str] = None,
) -> List[str]

返回此库中的符号。

参数	描述
regex	如果传入，则仅返回与正则表达式匹配的符号。 类型： Optional[str] 默认值： None
snapshot_name	返回快照下可用的符号。如果为 None，则考虑在当前时间点存在于库中的符号。 类型： Optional[str] 默认值： None

返回	描述
List[str]	库中的符号。

list_versions

list_versions(
    symbol: Optional[str] = None,
    snapshot: Optional[str] = None,
    latest_only: bool = False,
    skip_snapshots: bool = False,
) -> Dict[SymbolVersion, VersionInfo]

获取此库中的版本，按传入参数过滤。

参数	描述
symbol	要返回版本的符号。如果为 None，则返回库中所有符号的版本。 类型： Optional[str] 默认值： None
snapshot	仅返回命名快照中包含的版本。 类型： Optional[str] 默认值： None
latest_only	仅包含每个返回符号的最新版本。 类型： bool 默认值： False
skip_snapshots	不要用快照信息填充版本列表。如果快照很多，可以显著提高性能。 类型： bool 默认值： False

返回	描述
Dict[SymbolVersion, VersionInfo]	描述库中每个符号-版本对的版本的字典。由于符号版本是一个（命名）元组，您可以简单地像下面的示例所示那样索引到字典中。

示例

>>> df = pd.DataFrame()
>>> lib.write("symbol", df, metadata=10)
>>> lib.write("symbol", df, metadata=11, prune_previous_versions=False)
>>> lib.snapshot("snapshot")
>>> lib.write("symbol", df, metadata=12, prune_previous_versions=False)
>>> lib.delete("symbol", versions=(1, 2))
>>> versions = lib.list_versions("symbol")
>>> versions["symbol", 1].deleted
True
>>> versions["symbol", 1].snapshots
["my_snap"]

options

options() -> LibraryOptions

在此库上设置的库选项。另请参阅 enterprise_options。

prune_previous_versions

prune_previous_versions(symbol)

从数据库中删除给定符号的所有（非快照）版本，但最新版本除外。

参数	描述
symbol	要修剪的符号名称。 类型： `str`

read

read(
    symbol: str,
    as_of: Optional[AsOf] = None,
    date_range: Optional[
        Tuple[Optional[Timestamp], Optional[Timestamp]]
    ] = None,
    row_range: Optional[Tuple[int, int]] = None,
    columns: Optional[List[str]] = None,
    query_builder: Optional[QueryBuilder] = None,
    lazy: bool = False,
) -> Union[VersionedItem, LazyDataFrame]

读取命名符号的数据。返回一个 VersionedItem 对象，其中包含数据和元数据元素（如传入 write）。

参数	描述
symbol	符号名称。 类型： str
as_of	返回数据在某个时间点 (as of) 的状态。None 表示应读取最新版本。此参数的各种类型含义： - int：特定版本号。支持负索引，-1 表示最新版本，-2 表示前一个版本等。 - str：包含该版本的快照名称 - datetime.datetime：在请求时间点 as_of 存在的数据版本 类型： AsOf 默认值： None
date_range	限制读取数据的日期范围。 仅适用于时间索引的 Pandas dataframes 或 series。仅返回落在给定范围（包括）内的数据部分。任一端为 None 会使该范围部分保持开放。因此，指定 (None, datetime(2025, 1, 1) 表示您希望读取直到并包括 20250101 的所有数据。使用 QueryBuilder 类的 date_range 子句也可以实现相同的效果，这会更慢，但返回的数据内存占用更小。有关更多详细信息，请参阅 QueryBuilder.date_range 的文档字符串。 只能提供 date_range 或 row_range 中的一个。 类型： Optional[Tuple[Optional[Timestamp], Optional[Timestamp]]] 默认值： None
row_range	要读取数据的行范围。包含下限，不包含上限。lib.read(symbol, row_range=(start, end)).data 的行为应与 df.iloc[start:end] 相同，包括对负数 start/end 值的处理。 只能提供 date_range 或 row_range 中的一个。 类型： Optional[Tuple[int, int]] 默认值： None
columns	仅适用于 Pandas 数据。确定要返回哪些列的数据。特殊值： - None：返回包含所有列的 dataframe - []：返回仅包含索引列的 dataframe 类型： Optional[List[str]] 默认值： None
query_builder	在 dataframe 返回之前应用于它的 QueryBuilder 对象。有关更多信息，请参阅 QueryBuilder 类的文档 (from arcticdb import QueryBuilder; help(QueryBuilder))。 类型： Optional[QueryBuilder] 默认值： None
lazy	将查询执行延迟到对返回的 LazyDataFrame 对象调用 collect 时。有关更多详细信息，请参阅 LazyDataFrame 的文档。 类型： bool 默认值： False

返回	描述
Union[VersionedItem, LazyDataFrame]	如果 lazy 为 False，则返回 VersionedItem 对象，其中包含 .data 和 .metadata 元素。如果 lazy 为 True，则返回一个 LazyDataFrame 对象，可以在 collect 之前在其上执行进一步的查询。

示例

>>> df = pd.DataFrame({'column': [5,6,7]})
>>> lib.write("symbol", df, metadata={'my_dictionary': 'is_great'})
>>> lib.read("symbol").data
   column
0       5
1       6
2       7

默认的读取行为也可以通过下标访问来实现

>>> lib["symbol"].data
   column
0       5
1       6
2       7

read_batch

read_batch(
    symbols: List[Union[str, ReadRequest]],
    query_builder: Optional[QueryBuilder] = None,
    lazy: bool = False,
) -> Union[
    List[Union[VersionedItem, DataError]],
    LazyDataFrameCollection,
]

读取多个符号。

参数	描述
symbols	要读取的符号列表。 类型： List[Union[str, ReadRequest]]
query_builder	一个 QueryBuilder，在返回所有 dataframe 之前应用于它们。如果传入此参数，则 symbols 中的任何请求都不得指定自己的 query_builder。 类型： Optional[QueryBuilder] 默认值： None
lazy	将查询执行延迟到对返回的 LazyDataFrameCollection 对象调用 collect 时。有关更多详细信息，请参阅 LazyDataFrameCollection 的文档。 类型： bool 默认值： False

返回	描述
Union[List[Union[VersionedItem, DataError]], LazyDataFrameCollection]	如果 lazy 为 False：读取结果列表，其第 i 个元素对应于 symbols 参数的第 i 个元素。如果指定版本不存在，则返回一个 DataError 对象，其中包含 symbol、version_request_type、version_request_data 属性、error_code、error_category 和 exception_string 属性。如果发生键错误或任何其他内部异常，也会返回相同的 DataError 对象。如果 lazy 为 True：一个 LazyDataFrameCollection 对象，可以在 collection 之前在其上执行进一步的查询。

抛出	描述
ArcticInvalidApiUsageException	如果同时使用了 kwarg query_builder 和每符号 query builder。

示例

>>> lib.write("s1", pd.DataFrame())
>>> lib.write("s2", pd.DataFrame({"col": [1, 2, 3]}))
>>> lib.write("s2", pd.DataFrame(), prune_previous_versions=False)
>>> lib.write("s3", pd.DataFrame())
>>> batch = lib.read_batch(["s1", adb.ReadRequest("s2", as_of=0), "s3", adb.ReadRequest("s2", as_of=1000)])
>>> batch[0].data.empty
True
>>> batch[1].data.empty
False
>>> batch[2].data.empty
True
>>> batch[3].symbol
"s2"
>>> isinstance(batch[3], adb.DataError)
True
>>> batch[3].version_request_type
VersionRequestType.SPECIFIC
>>> batch[3].version_request_data
1000
>>> batch[3].error_code
ErrorCode.E_NO_SUCH_VERSION
>>> batch[3].error_category
ErrorCategory.MISSING_DATA

另请参阅

read

read_batch_and_join

read_batch_and_join(
    symbols: List[ReadRequest], query_builder: QueryBuilder
) -> VersionedItemWithJoin

批量读取多个符号，然后使用 query_builder 参数中的第一个子句将它们连接在一起。如果 query_builder 参数中有后续子句，则这些子句将应用于连接后的数据。

参数	描述
symbols	要读取的符号列表。 类型： List[Union[str, ReadRequest]]
query_builder	第一个子句必须是多符号连接，例如 concat。任何后续子句必须作用于单个 dataframe，并将应用于连接后的数据。 类型： QueryBuilder

返回	描述
VersionedItemWithJoin	包含一个带有连接数据的 .data 字段，以及一个描述已连接符号的版本号、元数据等的 VersionedItem 对象列表。

抛出	描述
UserInputException	如果 query_builder 中的第一个子句不是多符号连接 如果 query_builder 中的任何后续子句不是单符号子句 如果任何指定符号被递归标准化
MissingDataException	如果在 as_ofs 中指定的符号或符号版本不存在或已被删除
SchemaException	如果要连接的符号的模式不兼容。不兼容模式的示例包括 尝试将 Series 连接到 DataFrame 不同的索引类型，包括具有不同级别数的 MultiIndexes 不兼容的列类型，例如将字符串列连接到整数列

示例

将两个符号连接在一起，无需任何预处理或后处理。

>>> df0 = pd.DataFrame(
    {
        "col1": [0.5],
        "col2": [1],
    },
    index=[pd.Timestamp("2025-01-01")],
)
>>> df1 = pd.DataFrame(
    {
        "col3": ["hello"],
        "col2": [2],
    },
    index=[pd.Timestamp("2025-01-02")],
)
>>> q = adb.QueryBuilder()
>>> q = q.concat("outer")
>>> lib.write("symbol0", df0)
>>> lib.write("symbol1", df1)
>>> lib.read_batch_and_join(["symbol0", "symbol1"], query_builder=q).data

                       col1     col2     col3
2025-01-01 00:00:00     0.5        1     None
2025-01-02 00:00:00     NaN        2  "hello"

>>> q = adb.QueryBuilder()
>>> q = q.concat("inner")
>>> lib.read_batch_and_join(["symbol0", "symbol1"], query_builder=q).data

                       col2
2025-01-01 00:00:00       1
2025-01-02 00:00:00       2

read_metadata

read_metadata(
    symbol: str, as_of: Optional[AsOf] = None
) -> VersionedItem

返回为符号保存的元数据。此方法比 read 快，因为它只加载元数据，不加载数据本身。

参数	描述
symbol	符号名称 类型： str
as_of	返回数据在某个时间点 (as of) 的元数据。有关此参数可以采用的不同形式的文档，请参阅 read 的文档。 类型： AsOf 默认值： None

返回	描述
VersionedItem	包含存储中受影响符号的元数据和版本号的结构。data 属性将为 None。

read_metadata_batch

read_metadata_batch(
    symbols: List[Union[str, ReadInfoRequest]],
) -> List[Union[VersionedItem, DataError]]

读取多个符号的元数据。

参数	描述
symbols	要读取元数据的符号列表。 类型： List[Union[str, ReadInfoRequest]]

返回	描述
List[Union[VersionedItem, DataError]]	读取元数据结果列表，其第 i 个元素对应于 symbols 参数的第 i 个元素。如果请求的符号版本存在但没有元数据，将返回一个 VersionedItem 对象，其中 metadata 字段设置为 None。如果指定版本不存在，则返回一个 DataError 对象，其中包含 symbol、version_request_type、version_request_data 属性、error_code、error_category 和 exception_string 属性。如果发生键错误或任何其他内部异常，也会返回相同的 DataError 对象。

另请参阅

read_metadata

reload_symbol_list

reload_symbol_list()

强制重新加载符号列表缓存。

这在大型库或某些 S3 实现上可能需要很长时间，并且一旦开始，无法安全中断。如果调用以某种方式中断（异常/进程被杀死），请尽快再次调用此方法。

snapshot

snapshot(
    snapshot_name: str,
    metadata: Any = None,
    skip_symbols: Optional[List[str]] = None,
    versions: Optional[Dict[str, int]] = None,
) -> None

创建库中数据的命名快照。

默认情况下，快照将包含每个未删除符号的最新版本。您可以使用 versions（允许列表）或使用 skip_symbols（拒绝列表）更改此行为。在拍摄快照时设置了修剪先前版本选项的并发写入可能会导致快照中受影响的符号损坏。

快照中包含的符号和版本将持久存在，无论之后是否向库写入新的符号和版本。如果快照中引用的版本或符号被删除，则底层数据将保留以确保快照仍然可访问。只有当所有引用快照都被删除后，底层数据才会被删除。

skip_symbols 和 versions 中最多只能有一个为真值。

参数	描述
snapshot_name	快照的名称。 类型： str
metadata	要与快照一起持久化的可选元数据。 类型： Any 默认值： None
skip_symbols	要从快照中排除的可选符号。 类型： List[str] 默认值： None
versions	要创建快照的符号版本可选字典。例如，versions={"a": 2, "b": 3} 将对符号 "a" 的版本 2 和符号 "b" 的版本 3 创建快照。 类型： Optional[Dict[str, int]] 默认值： None

抛出	描述
InternalException	如果已存在名称为 snapshot_name 的快照。您必须明确删除预先存在的快照。
MissingDataException	如果在 versions 中指定的符号或符号版本在库中不存在或已被删除，或者库中没有符号时。

sort_and_finalize_staged_data

sort_and_finalize_staged_data(
    symbol: str,
    mode: Optional[StagedDataFinalizeMethod] = WRITE,
    prune_previous_versions: bool = False,
    metadata: Any = None,
    delete_staged_data_on_failure: bool = False,
) -> VersionedItem

对所有暂存数据进行排序和合并，使其可供读取。这与 finalize_staged_data 的区别在于它可以支持时间段交错的暂存段以及未在内部排序的暂存段。最终结果将是排序的。这需要在内存中执行完整排序，因此可能耗时。

如果 mode 是 StagedDataFinalizeMethod.APPEND，则排序块的第一行的索引必须等于或大于现有数据中最后一行的索引。

如果使用 Static Schema，则所有暂存块必须具有匹配的模式（相同的列名、相同的 dtype、相同的列顺序），并且如果模式是 StagedDataFinalizeMethod.APPEND，则必须与现有数据匹配。有关模式选项的更多信息，请参阅 arcticdb.LibraryOptions.dynamic_schema 的文档。

如果符号不存在，StagedDataFinalizeMethod.APPEND 和 StagedDataFinalizeMethod.WRITE 都会创建它。

如果在符号没有暂存数据的情况下调用 sort_and_finalize_staged_data，将抛出 UserInputException。使用 get_staged_symbols 检查符号是否存在暂存段。

如果在任何暂存段的索引中包含 NaT 时调用 sort_and_finalize_staged_data，将抛出 SortingException。

参数	描述
symbol	要最终确定数据的符号。 类型： str
mode	最终确定模式。有效选项为 WRITE 或 APPEND。Write 收集暂存数据并将其写入新的时间序列。Append 收集暂存数据并将其追加到最新版本。 类型： `StagedDataFinalizeMethod` 默认值： StagedDataFinalizeMethod.WRITE
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
metadata	要与符号一起持久化的可选元数据。 类型： Any 默认值： None
delete_staged_data_on_failure	确定在执行 sort_and_finalize_staged_data 函数期间发生异常时如何处理暂存数据。 如果设置为 True，则在发生异常时将删除指定符号的所有暂存数据。 如果设置为 False，则将保留暂存数据，并在后续调用 sort_and_finalize_staged_data 中使用。 要手动删除暂存数据，请使用 delete_staged_data 函数。 类型： bool 默认值： False

返回	描述
VersionedItem	包含存储中写入符号的元数据和版本号的结构。data 成员将为 None。

抛出	描述
SortingException	当使用 StagedDataFinalizeMethod.APPEND 时，如果排序块的第一个索引值不大于或等于现有数据中最后一个索引值。 如果任何暂存段的索引包含 NaT
UserInputException	在调用 sort_and_finalize_staged_data 时没有暂存段时 如果满足以下所有条件 使用了静态模式。 DataFrame 的宽度超过 LibraryOptions.columns_per_segment 的值。 该符号包含并非由 sort_and_finalize_staged_data 写入的数据。 最终确定模式为 append
SchemaException	如果使用静态模式且并非所有暂存段都具有匹配的模式。 如果使用静态模式，模式为 StagedDataFinalizeMethod.APPEND，并且排序合并后的暂存段的模式与现有数据的模式不同 如果使用动态模式，并且不同段具有相同的列名但其 dtypes 没有共同类型（例如字符串和任何数字类型） 如果在暂存数据中遇到不同的索引名称，无论模式模式如何

另请参阅

write 关于 staged 参数的文档更详细地解释了暂存数据的概念。

示例

>>> lib.write("sym", pd.DataFrame({"col": [2, 4]}, index=pd.DatetimeIndex([pd.Timestamp(2024, 1, 2), pd.Timestamp(2024, 1, 4)])), staged=True)
>>> lib.write("sym", pd.DataFrame({"col": [3, 1]}, index=pd.DatetimeIndex([pd.Timestamp(2024, 1, 3), pd.Timestamp(2024, 1, 1)])), staged=True)
>>> lib.sort_and_finalize_staged_data("sym")
>>> lib.read("sym").data
            col
2024-01-01    1
2024-01-02    2
2024-01-03    3
2024-01-04    4

stage

stage(
    symbol: str,
    data: NormalizableType,
    validate_index=True,
    sort_on_index=False,
    sort_columns: List[str] = None,
)

将暂存数据块写入存储，在对符号调用 finalize_staged_data 之前不可见。等同于将 write() 的 staged 参数设置为 True。

参数	描述
symbol	符号名称。限制为 255 个字符。符号中不支持以下字符："*", "&", "<", ">" 类型： str
data	要写入的数据。暂存数据必须是可标准化的。 类型： NormalizableType
validate_index	写入前检查索引是否已排序。对于未排序的数据，抛出 UnsortedDataException 默认值： True
sort_on_index	如果存在合适的索引，则按索引对数据进行排序。与 sort_columns 结合使用时，索引将用作主排序列，其他列用作次级排序列。 默认值： False
sort_columns	写入前按特定列对数据进行排序。 类型： List[str] 默认值： None

tail

tail(
    symbol: str,
    n: int = 5,
    as_of: Optional[Union[int, str]] = None,
    columns: List[str] = None,
    lazy: bool = False,
) -> Union[VersionedItem, LazyDataFrame]

读取命名符号数据的最后 n 行。如果 n 为负数，则返回除前 n 行之外的所有行。

参数	描述
symbol	符号名称。 类型： str
n	如果要选择的行数是非负数，否则是要排除的行数。 类型： int 默认值： 5
as_of	请参阅 read 的文档。 类型： AsOf 默认值： None
columns	请参阅 read 的文档。 类型： List[str] 默认值： None
lazy	请参阅 read 的文档。 类型： bool 默认值： False

返回	描述
Union[VersionedItem, LazyDataFrame]	如果 lazy 为 False，则返回 VersionedItem 对象，其中包含 .data 和 .metadata 元素。如果 lazy 为 True，则返回一个 LazyDataFrame 对象，可以在 collect 之前在其上执行进一步的查询。

update

update(
    symbol: str,
    data: Union[DataFrame, Series],
    metadata: Any = None,
    upsert: bool = False,
    date_range: Optional[
        Tuple[Optional[Timestamp], Optional[Timestamp]]
    ] = None,
    prune_previous_versions: bool = False,
) -> VersionedItem

用 data 的内容覆盖现有的符号数据。data 中第一个索引条目和最后一个索引条目之间的整个范围将被 data 的内容完全替换，如果需要则添加额外的索引条目。update 只作用于最外层的索引级别 - 这意味着如果不包含在 data 中，次级索引行将被删除。

现有的符号版本和 data 都必须是时间序列索引的。

在 data 行数为零的情况下，将不执行任何操作，也不会创建新版本。这意味着不能将 update 与 date_range 一起使用来仅删除部分数据。我们有专门用于此目的的 delete_data_in_range，以明确表明何时是删除操作。

请注意，update 不支持对单个符号进行多个并发写入。

如果使用静态模式，则 data 的所有列名、它们的顺序和类型必须与存储中已有的列匹配。

如果使用动态模式，则数据将覆盖 data 的整个索引范围内的存储中的所有内容。Update 不会保留存储中不在 data 中的列。

更新操作将分割存储中与 'data' 相交的第一个和最后一个段。因此，频繁调用 update 可能会导致数据碎片化（参见下面的示例）。

参数	描述
symbol	符号名称。 类型： str
data	用于更新的时间序列索引数据。 类型： Union[DataFrame, Series]
metadata	要与新符号版本一起持久化的元数据。 类型： Any 默认值： None
upsert	如果为 True，则即使符号不存在，也会写入数据。 类型： bool 默认值： False
date_range	如果指定了范围，它将删除该范围内的存储值，并用 data 中的数据覆盖它。这允许用户使用可能只是存储值子集的数据进行更新。将元组的任何部分留空为 None 会使该部分的范围保持开放。即使 data 涵盖更宽的日期范围，也仅修改具有 date_range 的数据。 类型： Optional[Tuple[Optional[Timestamp], Optional[Timestamp]]] 默认值： None
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False

返回	描述
VersionedItem	包含存储中写入符号的元数据和版本号的结构。

示例

>>> df = pd.DataFrame(
...    {'column': [1,2,3,4]},
...    index=pd.date_range(start='1/1/2018', end='1/4/2018')
... )
>>> df
            column
2018-01-01       1
2018-01-02       2
2018-01-03       3
2018-01-04       4
>>> lib.write("symbol", df)
>>> update_df = pd.DataFrame(
...    {'column': [400, 40]},
...    index=pd.date_range(start='1/1/2018', end='1/3/2018', freq='2D')
... )
>>> update_df
            column
2018-01-01     400
2018-01-03      40
>>> lib.update("symbol", update_df)
>>> # Note that 2018-01-02 is gone despite not being in update_df
>>> lib.read("symbol").data
            column
2018-01-01     400
2018-01-03      40
2018-01-04       4

Update 将分割与 data 相交的第一个和最后一个段

>>> index = pd.date_range(pd.Timestamp("2024-01-01"), pd.Timestamp("2024-02-01"))
>>> df = pd.DataFrame({f"col_{i}": range(len(index)) for i in range(1)}, index=index)
>>> lib.write("test", df)
>>> lt=lib._dev_tools.library_tool()
>>> print(lt.read_index("test"))
start_index                     end_index  version_id stream_id          creation_ts         content_hash  index_type  key_type  start_col  end_col  start_row  end_row
2024-01-01  2024-02-01 00:00:00.000000001           0   b'test'  1738599073224386674  9652922778723941392          84         2          1        2          0       32
>>> update_index=pd.date_range(pd.Timestamp("2024-01-10"), freq="ns", periods=200000)
>>> update = pd.DataFrame({f"col_{i}": [1] for i in range(1)}, index=update_index)
>>> lib.update("test", update)
>>> print(lt.read_index("test"))
start_index                                    end_index  version_id stream_id          creation_ts          content_hash  index_type  key_type  start_col  end_col  start_row  end_row
2024-01-01 00:00:00.000000 2024-01-09 00:00:00.000000001           1   b'test'  1738599073268200906  13838161946080117383          84         2          1        2          0        9
2024-01-10 00:00:00.000000 2024-01-10 00:00:00.000100000           1   b'test'  1738599073256354553  15576483210589662891          84         2          1        2          9   100009
2024-01-10 00:00:00.000100 2024-01-10 00:00:00.000200000           1   b'test'  1738599073256588040  12429442054752910013          84         2          1        2     100009   200009
2024-01-11 00:00:00.000000 2024-02-01 00:00:00.000000001           1   b'test'  1738599073268493107   5975110026983744452          84         2          1        2     200009   200031

update_batch

update_batch(
    update_payloads: List[UpdatePayload],
    upsert: bool = False,
    prune_previous_versions: bool = False,
) -> List[Union[VersionedItem, DataError]]

并行对符号列表执行更新操作。所有 update 的约束也适用于此调用。

参数	描述
update_payloads	列表 arcticdb.library.UpdatePayload。列表中的每个元素描述了特定符号的更新操作，提供了符号名称、数据等。此列表中不应出现相同的符号两次。 类型： List[UpdatePayload]
prune_previous_versions	从库中删除之前的（非快照）版本。 类型： bool 默认值： False
upsert	如果为 True，则 update_payloads 中任何不在库中的符号都将被创建。 类型： bool 默认值： False

返回	描述
List[Union[VersionedItem, DataError]]	版本化项目列表。第 i 个条目对应于 update_payloads 的第 i 个元素。每个结果对应于一个包含存储中受影响符号的元数据和版本号的结构。如果发生键错误或任何其他内部异常，则返回一个 DataError 对象，其中包含 symbol、error_code、error_category 和 exception_string 属性。

抛出	描述
ArcticDuplicateSymbolsInBatchException	当负载中出现重复符号时。
ArcticUnsupportedDataTypeException	如果在任何负载中出现不是 NormalizableType 的数据时。

示例

>>> df1 = pd.DataFrame({'column_1': [1, 2, 3]}, index=pd.date_range("2025-01-01", periods=3))
>>> df1
            column_1
2025-01-01         1
2025-01-02         2
2025-01-03         3
>>> df2 = pd.DataFrame({'column_2': [10, 11]}, index=pd.date_range("2024-01-01", periods=2))
>>> df2
            column_2
2024-01-01        10
2024-01-02        11
>>> lib.write("symbol_1", df1)
>>> lib.write("symbol_2", df1)
>>> lib.update_batch([arcticdb.library.UpdatePayload("symbol_1", pd.DataFrame({"column_1": [4, 5]}, index=pd.date_range("2025-01-03", periods=2))), arcticdb.library.UpdatePayload("symbol_2", pd.DataFrame({"column_2": [-1]}, index=pd.date_range("2023-01-01", periods=1)))])
[VersionedItem(symbol='symbol_1', library='test', data=n/a, version=1, metadata=(None,), host='LMDB(path=...)', timestamp=1737542783853861819), VersionedItem(symbol='symbol_2', library='test', data=n/a, version=1, metadata=(None,), host='LMDB(path=...)', timestamp=1737542783851798754)]
>>> lib.read("symbol_1").data
            column_1
2025-01-01         1
2025-01-02         2
2025-01-03         4
2025-01-04         5
>>> lib.read("symbol_2").data
            column_2
2023-01-01        -1
2024-01-01        10
2024-01-02        11

write

write(
    symbol: str,
    data: NormalizableType,
    metadata: Any = None,
    prune_previous_versions: bool = False,
    staged=False,
    validate_index=True,
) -> VersionedItem

将 data 写入指定的 symbol。如果 symbol 已存在，则将创建新版本来引用新写入的数据。有关版本的更多信息，请参阅 read 基本操作的文档。

data 必须是能够标准化为 Arctic 内部存储结构的格式。Pandas DataFrames、Pandas Series 和 Numpy NDArrays 都可以标准化。标准化数据将沿着列和行分割成段。默认情况下，一个段将包含 100,000 行和 127 列。

如果此库启用了 write_deduplication，则在写入前将对段进行去重，以减少所需的 IO 操作和存储需求。与存储相比，直到第一行不同，所有段的数据都将有效去重。因此，相对于之前写入的版本修改 data 的开头可能会显著降低去重效果。

请注意，write 不支持对单个符号进行多个并发写入，除非将 staged 关键字参数设置为 True。如果 staged 为 True，则写入的段将暂存并保持在“不完整”状态，直到最终确定后才能读取。这使得多个写操作可以对单个符号同时进行 - 所有写入都同时写入暂存数据 - 然后一个进程可以稍后最终确定所有暂存数据，使数据可供客户端读取。要最终确定暂存数据，请参阅 finalize_staged_data。

注意：ArcticDB 将使用 Pandas DataFrame 的 0 级索引作为其磁盘索引。

任何非 DatetimeIndex 都将转换为内部 RowCount 索引。也就是说，ArcticDB 将为每一行分配一个单调递增的整数标识符，并将其用作索引。

有关元数据如何持久化以及注意事项的详细信息，请参阅我们在线文档的元数据部分。

参数	描述
symbol	符号名称。限制为 255 个字符。符号中不支持以下字符："*", "&", "<", ">" 类型： str
data	要写入的数据。要写入不可标准化的数据，请使用 write_pickle。 类型： NormalizableType
metadata	要与符号一起持久化的可选元数据。 类型： Any 默认值： None
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
staged	是否写入暂存区域而不是立即写入库。有关更多信息，请参阅 finalize_staged_data 的文档。 类型： bool 默认值： False
validate_index	如果为 True，则验证 data 的索引是否支持日期范围搜索和更新操作。这会测试数据是否按升序排序，使用 Pandas DataFrame.index.is_monotonic_increasing。 默认值： True

返回	描述
VersionedItem	包含存储中写入符号的元数据和版本号的结构。

抛出	描述
ArcticUnsupportedDataTypeException	如果 data 不是 NormalizableType。
UnsortedDataException	如果数据未排序且 validate_index 设置为 True 时。

示例

>>> df = pd.DataFrame({'column': [5,6,7]})
>>> lib.write("symbol", df, metadata={'my_dictionary': 'is_great'})
>>> lib.read("symbol").data
   column
0       5
1       6
2       7

暂存数据以供稍后最终确定（启用并发写入）

>>> df = pd.DataFrame({'column': [5,6,7]}, index=pd.date_range(start='1/1/2000', periods=3))
>>> lib.write("staged", df, staged=True)  # Multiple staged writes can occur in parallel
>>> lib.finalize_staged_data("staged", StagedDataFinalizeMethod.WRITE)  # Must be run after all staged writes have completed
>>> lib.read("staged").data  # Would return error if run before finalization
            column
2000-01-01       5
2000-01-02       6
2000-01-03       7

WritePayload 对象可以解包并用作参数

>>> w = adb.WritePayload("symbol", df, metadata={'the': 'metadata'})
>>> lib.write(*w, staged=True)

write_batch

write_batch(
    payloads: List[WritePayload],
    prune_previous_versions: bool = False,
    validate_index=True,
) -> List[Union[VersionedItem, DataError]]

批量写入多个符号。

参数	描述
payloads	符号及其对应的数据。payload 中不得有重复的符号。 类型： `List[WritePayload]`
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False
validate_index	验证批处理中的每个条目都有一个支持日期范围搜索和更新操作的索引。这会测试数据是否按升序排序，使用 Pandas DataFrame.index.is_monotonic_increasing。 默认值： True

返回	描述
List[Union[VersionedItem, DataError]]	版本化项目列表。每个版本化项目的 data 属性将为 None。第 i 个条目对应于 payloads 的第 i 个元素。每个结果对应于一个包含存储中写入符号的元数据和版本号的结构，顺序与 payload 相同。如果发生键错误或任何其他内部异常，则返回一个 DataError 对象，其中包含 symbol、error_code、error_category 和 exception_string 属性。

抛出	描述
ArcticDuplicateSymbolsInBatchException	当负载中出现重复符号时。
ArcticUnsupportedDataTypeException	如果在任何负载中出现不是 NormalizableType 的数据时。

另请参阅

write：有关更详细的文档。

示例

写入简单的批处理

>>> df_1 = pd.DataFrame({'column': [1,2,3]})
>>> df_2 = pd.DataFrame({'column': [4,5,6]})
>>> payload_1 = adb.WritePayload("symbol_1", df_1, metadata={'the': 'metadata'})
>>> payload_2 = adb.WritePayload("symbol_2", df_2)
>>> items = lib.write_batch([payload_1, payload_2])
>>> lib.read("symbol_1").data
   column
0       1
1       2
2       3
>>> lib.read("symbol_2").data
   column
0       4
1       5
2       6
>>> items[0].symbol, items[1].symbol
('symbol_1', 'symbol_2')

write_metadata

write_metadata(
    symbol: str,
    metadata: Any,
    prune_previous_versions: bool = False,
) -> VersionedItem

将指定符号名称下的元数据写入此库。数据将保持不变。将创建新版本。

如果符号缺失，它将导致写入空数据（None，pickle 序列化，不可追加）和提供的元数据。

此方法应比 write 快，因为它不涉及数据段的读/写操作。

有关元数据如何持久化以及注意事项的详细信息，请参阅我们在线文档的元数据部分。

参数	描述
symbol	项目的符号名称 类型： str
metadata	要与符号一起持久化的元数据 类型： Any
prune_previous_versions	从数据库中删除之前的（非快照）版本。请注意，元数据与其引用的数据一起进行版本控制，因此此操作会删除旧版本的数据以及元数据。 类型： bool 默认值： False

返回	描述
VersionedItem	包含存储中受影响符号的元数据和版本号的结构。

write_metadata_batch

write_metadata_batch(
    write_metadata_payloads: List[WriteMetadataPayload],
    prune_previous_versions: bool = False,
) -> List[Union[VersionedItem, DataError]]

以批量方式向多个符号写入元数据。这比连续调用多次 write_metadata 更高效，因为一些常数时间的操作可以只执行一次，而不是对 write_metadata_payloads 中的每个元素都执行一次。请注意，这不是一个原子操作 - 有可能一个符号的元数据完全写入并可读后，另一个符号才开始写入。

有关元数据如何持久化以及注意事项的详细信息，请参阅我们在线文档的元数据部分。

参数	描述
write_metadata_payloads	符号及其对应的元数据。payload 中不得有重复的符号。 类型： `List[WriteMetadataPayload]`
prune_previous_versions	从数据库中删除之前的（非快照）版本。请注意，元数据与其引用的数据一起进行版本控制，因此此操作会删除旧版本的数据以及元数据。 类型： bool 默认值： False

返回	描述
List[Union[VersionedItem, DataError]]	版本化项目列表。每个版本化项目的 data 属性将为 None。第 i 个条目对应于 write_metadata_payloads 的第 i 个元素。每个结果对应于一个包含存储中受影响符号的元数据和版本号的结构。如果发生任何内部异常，则返回一个 DataError 对象，其中包含 symbol、error_code、error_category 和 exception_string 属性。

抛出	描述
ArcticDuplicateSymbolsInBatchException	当 write_metadata_payloads 中出现重复符号时。

示例

写入简单的批处理

>>> payload_1 = adb.WriteMetadataPayload("symbol_1", {'the': 'metadata_1'})
>>> payload_2 = adb.WriteMetadataPayload("symbol_2", {'the': 'metadata_2'})
>>> items = lib.write_metadata_batch([payload_1, payload_2])
>>> lib.read_metadata("symbol_1")
{'the': 'metadata_1'}
>>> lib.read_metadata("symbol_2")
{'the': 'metadata_2'}

write_pickle

write_pickle(
    symbol: str,
    data: Any,
    metadata: Any = None,
    prune_previous_versions: bool = False,
    staged=False,
) -> VersionedItem

请参阅 write。此方法与 write 的不同之处仅在于 data 可以是通过 Pickle 库序列化的任何类型。以这种方式存储数据存在显著的缺点

• 只能批量检索。调用 read 不支持 date_range、query_builder 或 columns。
• 数据无法通过 update 和 append 方法进行更新或追加。
• 写入无法进行任何方式的去重。

参数	描述
symbol	请参阅 write 的文档。 类型： str
data	要写入的数据。 类型： `Any`
metadata	请参阅 write 的文档。 类型： Any 默认值： None
prune_previous_versions	请参阅 write 的文档。 类型： bool 默认值： False
staged	请参阅 write 的文档。 默认值： False

返回	描述
VersionedItem	请参阅 write 的文档。

示例

>>> lib.write_pickle("symbol", [1,2,3])
>>> lib.read("symbol").data
[1, 2, 3]

另请参阅

write：有关更详细的文档。

write_pickle_batch

write_pickle_batch(
    payloads: List[WritePayload],
    prune_previous_versions: bool = False,
) -> List[Union[VersionedItem, DataError]]

批量写入多个符号，如果需要则对其数据进行 pickle 序列化。

参数	描述
payloads	符号及其对应的数据。payload 中不得有重复的符号。 类型： `List[WritePayload]`
prune_previous_versions	从数据库中删除之前的（非快照）版本。 类型： bool 默认值： False

返回	描述
List[Union[VersionedItem, DataError]]	包含存储中写入符号的元数据和版本号的结构，顺序与 payload 相同。如果发生键错误或任何其他内部异常，则返回一个 DataError 对象，其中包含 symbol、error_code、error_category 和 exception_string 属性。

抛出	描述
ArcticDuplicateSymbolsInBatchException	当负载中出现重复符号时。

另请参阅

write: 有关更详细的文档。 write_pickle: 有关需要进行 pickle 序列化的数据提供的影响的信息。