Arctic API¶

用于访问和管理 ArcticDB library 的主要 API。使用此 API 获取一个 Library 实例的句柄，然后可以使用该实例进行 Library API 部分文档中记载的后续操作。

类	描述
Arctic	顶级 library 管理类。
LibraryOptions	创建 library 时可以应用的配置选项。

arcticdb.Arctic ¶

顶级 library 管理类。 Arctic 实例可以针对 S3 环境进行配置，并支持 Arctic library 的创建、删除和检索。

方法	描述
`__init__`	初始化一个顶级的 Arctic library 管理实例。
`create_library`	创建名为 `name` 的 library。
`delete_library`	删除名为 `name` 的 library。此操作将删除 library 中包含的底层数据，因此将花费底层删除操作所需的时间。
`get_library`	返回名为 `name` 的 library。
`get_uri`	返回用于创建 Arctic 实例的 URI。
`has_library`	查询给定 library 是否存在
`list_libraries`	列出所有可用的 library。
`modify_library_option`	修改 library 的一个选项。

init ¶

__init__(
    uri: str,
    encoding_version: EncodingVersion = DEFAULT_ENCODING_VERSION,
)

初始化一个顶级的 Arctic library 管理实例。

有关如何使用 Arctic Library 实例的更多信息，请参阅 Library 文档。

参数	描述
`uri`	指定用于访问、配置和创建 Arctic library 的后端存储的 URI。有关参数的更多详细信息，请参阅 Arctic URI 文档。类型： `str`
`encoding_version`	使用此 Arctic 实例创建新 library 时使用的默认编码版本。可以通过在 create_library 的 LibraryOptions 参数中指定编码版本来覆盖。类型： `EncodingVersion` 默认值： `DEFAULT_ENCODING_VERSION`

示例

>>> ac = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET')  # Leave AWS to derive credential information
>>> ac = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET?region=YOUR_REGION&access=ABCD&secret=DCBA') # Manually specify creds
>>> ac = adb.Arctic('azure://CA_cert_path=/etc/ssl/certs/ca-certificates.crt;BlobEndpoint=https://arctic.blob.core.windows.net;Container=acblob;SharedAccessSignature=sp=sig')
>>> ac.create_library('travel_data')
>>> ac.list_libraries()
['travel_data']
>>> travel_library = ac['travel_data']
>>> ac.delete_library('travel_data')

create_library ¶

create_library(
    name: str,
    library_options: Optional[LibraryOptions] = None,
    enterprise_library_options: Optional[
        EnterpriseLibraryOptions
    ] = None,
) -> Library

创建名为 name 的 library。

Arctic library 包含命名符号 (symbols)，符号是 Arctic 中数据存储的原子单元。符号包含的数据在大多数情况下与 DataFrame 非常相似，并且是版本化的，以便可以跟踪和回滚所有修改操作。

Arctic library 支持对多个符号进行并发写入和读取，以及对单个符号进行并发读取。但是，除了明确支持单符号并发写入的原语外，不支持对单个符号进行并发写入。

参数	描述
`name`	您希望创建的 library 的名称。类型： `str`
`library_options`	配置 library 时使用的选项。如果未提供，则默认值与 LibraryOptions 中记录的相同。类型： `Optional[LibraryOptions]` 默认值： `None`
`enterprise_library_options`	配置 library 时使用的企业版选项。如果未提供，则默认值与 EnterpriseLibraryOptions 中记录的相同。这些选项仅与 ArcticDB 企业版用户相关。类型： `Optional[EnterpriseLibraryOptions]` 默认值： `None`

示例

>>> arctic = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET')
>>> arctic.create_library('test.library')
>>> my_library = arctic['test.library']

返回值	描述
`刚刚创建的 library`

delete_library ¶

delete_library(name: str) -> None

删除名为 name 的 library。这将删除 library 中包含的底层数据，因此所需时间与底层删除操作所需时间相同。

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

参数	描述
`name`	要删除的 library 的名称。类型： `str`

get_library ¶

get_library(
    name: str,
    create_if_missing: Optional[bool] = False,
    library_options: Optional[LibraryOptions] = None,
) -> Library

返回名为 name 的 library。

此方法也可以通过下标调用。adb.Arctic('bucket').get_library("test") 等效于 adb.Arctic('bucket')["test"]。

参数	描述
`name`	您希望检索的 library 的名称。类型： `str`
`create_if_missing`	如果为 True，并且 library 不存在，则创建它。类型： `Optional[bool]` 默认值： `False`
`library_options`	如果 create_if_missing 为 True，且 library 不存在，则使用这些选项（或默认选项，如果未提供）创建它。如果 create_if_missing 为 True，且 library 已存在，则确保现有 library 选项与这些选项匹配。如果 create_if_missing 为 False，则不使用此选项。类型： `Optional[LibraryOptions]` 默认值： `None`

示例

>>> arctic = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET')
>>> arctic.create_library('test.library')
>>> my_library = arctic.get_library('test.library')
>>> my_library = arctic['test.library']

返回值	描述
`Library`

get_uri ¶

get_uri() -> str

返回用于创建 Arctic 实例的 URI。

示例

>>> arctic = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET')
>>> arctic.get_uri()

返回值	描述
`s3`	类型： `//MY_ENDPOINT:MY_BUCKET`

has_library ¶

has_library(name: str) -> bool

查询给定 library 是否存在

参数	描述
`name`	要检查是否存在的 library 的名称。类型： `str`

返回值	描述
`如果 library 存在则为 True，否则为 False。`

list_libraries ¶

list_libraries() -> List[str]

列出所有可用的 library。

示例

>>> arctic = adb.Arctic('s3://MY_ENDPOINT:MY_BUCKET')
>>> arctic.list_libraries()
['test.library']

返回值	描述
`此 Arctic 实例中存在的所有 library 名称的列表。`

modify_library_option ¶

modify_library_option(
    library: Library,
    option: Union[
        ModifiableLibraryOption,
        ModifiableEnterpriseLibraryOption,
    ],
    option_value: Any,
)

修改 library 的一个选项。

有关各种选项的含义说明，请参阅 LibraryOptions 和 EnterpriseLibraryOptions。

修改后，此进程以及打开该 library 的其他进程将使用新值。已经打开该 library 的进程需要重新启动才能看到配置更改。

参数	描述
`library`	要修改的 library。类型： `Library`
`option`	要更改的 library 选项。类型： `Union[ModifiableLibraryOption, ModifiableEnterpriseLibraryOption]`
`option_value`	library 选项的新设置。类型： `Any`

arcticdb.LibraryOptions ¶

ArcticDB library 的配置选项。

属性	描述
`dynamic_schema`	详见 `__init__`。类型： `bool`
`dedup`	详见 `__init__`。类型： `bool`
`rows_per_segment`	详见 `__init__`。类型： `int`
`columns_per_segment`	详见 `__init__`。类型： `int`

方法	描述
`__init__`	参数

init ¶

__init__(
    *,
    dynamic_schema: bool = False,
    dedup: bool = False,
    rows_per_segment: int = 100000,
    columns_per_segment: int = 127,
    encoding_version: Optional[EncodingVersion] = None
)

参数	描述
`dynamic_schema`	控制 library 是否支持动态更改符号模式 (symbol schemas)。符号的模式指的是列的顺序和列的类型。如果为 False，则符号的模式在每次 `write` 调用时设置，并且不能被后续的 update 或 append 操作修改。每次后续的 update 或 append 操作必须包含与初始 write 操作相同的列集，顺序和类型也必须相同。禁用此选项后，ArcticDB 将在行和列两个维度上对存储的数据进行分块。这使得无论符号中存储的总列数是多少，都能高效地检索特定列。如果为 True，则 update 和 append 操作可以包含在最近一次 write 调用中未曾出现的列。读取时，如果需要新列，数据将动态回填。此外，如果列的类型发生变化，Arctic 将支持数值类型提升——例如，如果列 A 在写入时是 int32 类型，在下一次 append 时是 float 类型，则在读取时会将该列作为 float 类型返回给 Pandas。支持的提升包括（窄）整数到（宽）整数，以及整数到 float。启用此选项后，ArcticDB 将仅在数据的行维度上进行分块。当存储大量列（>1,000）时，这将导致列子集检索变慢。类型： `bool` 默认值： `False`
`dedup`	控制对 write 和 write_batch 的调用是否会尝试根据指定符号的先前活动版本进行数据段去重。如果为 False，则创建的新版本符号将总是写入新的数据段。如果为 True，则会将与此符号的先前活动版本相关的数据段的内容哈希、起始索引和结束索引与即将写入的数据段进行比较，如果匹配，则不会在存储设备中重复。请记住，这在版本 n 等于版本 n-1 加上末尾的额外数据时最有效——并且只能在末尾添加数据！如果在开头或中间插入了额外数据，则在该修改之后出现的所有数据段几乎肯定会不同。ArcticDB 会在固定间隔创建新的数据段，并且只有当数据段的哈希完全相同时才会进行去重。因此，即使是一行数据的偏移也会阻止去重。注意，这些条件也将通过 write_pickle 和 write_pickle_batch 进行检查。但是， pickled 对象总是作为单个数据段写入，因此只有当写入的对象与先前版本完全相同时才会发生去重。类型： `bool` 默认值： `False`
`rows_per_segment`	与 columns_per_segment 一起，控制写入、append 或 update 的数据在写入存储之前如何被切分成单独的数据段对象。通过将数据分割成存储中的多个对象，包含 date_range 和/或 columns 参数的 read 和 read_batch 调用可以通过仅读取包含读取器请求数据的那些数据段来减少从存储读取的数据量。例如，如果写入一个包含 250,000 行和 200 列的 dataframe，默认情况下，这将切分成 6 个数据段： 1 - 第 1-100,000 行和第 1-127 列 2 - 第 100,001-200,000 行和第 1-127 列 3 - 第 200,001-250,000 行和第 1-127 列 4 - 第 1-100,000 行和第 128-200 列 5 - 第 100,001-200,000 行和第 128-200 列 6 - 第 200,001-250,000 行和第 128-200 列覆盖相同行范围的数据段属于同一个行切片（例如上例中的段 2 和 5）。覆盖相同列范围的数据段属于同一个列切片（例如上例中的段 2 和 3）。请注意，此切片仅应用于正在写入的新数据，先前版本中可以保持不变的现有数据段不会被修改。例如，如果写入一个包含 50,000 行和一列的 dataframe，然后再 append 另一个同样包含 50,000 行和一列的 dataframe，则仍将有两个数据段，每个包含 50,000 行。请注意，对于启用了 dynamic_schema 的 library，columns_per_segment 不适用，并且始终只有一个列切片。但是，会使用 rows_per_segment，并且会有多个行切片。类型： `int` 默认值： `100000`
`columns_per_segment`	参见 rows_per_segment 类型： `int` 默认值： `127`
`encoding_version`	将数据写入存储时使用的编码版本。v2 速度更快，但仍处于实验阶段，请谨慎使用。类型： `Optional[EncodingVersion]` 默认值： `None`

Arctic API¶

arcticdb.Arctic ¶

__init__ ¶

create_library ¶

delete_library ¶

get_library ¶

get_uri ¶

has_library ¶

list_libraries ¶

modify_library_option ¶

arcticdb.LibraryOptions ¶

__init__ ¶

init ¶

init ¶