ArcticDB 基础¶

本教程将带您了解 ArcticDB 的基础知识

访问库
写入数据
读取数据
修改数据

首先，让我们导入 arcticdb

import arcticdb as adb

访问库¶

连接到您的存储

# Connect using defined keys
ac = adb.Arctic('s3s://s3.eu-west-2.amazonaws.com:arctic-test-aws?access=<access key>&secret=<secret key>')
# Leave AWS SDK to work out auth details 
ac = adb.Arctic('s3s://s3.eu-west-2.amazonaws.com:arctic-test-aws?aws_auth=true)

有关 AWS SDK 如何在不使用定义密钥的情况下配置身份验证的更多信息，请参阅 AWS 文档。

使用 [library_name] 表示法或 get_library 方法访问库

lib = ac['library']
# ...equivalent to...
lib = ac.get_library['library']

让我们看看有哪些数据已经存在

>>> lib.list_symbols()
['sym_2', 'sym_1', 'symbol']

ArcticDB API¶

ArcticDB 的 API 基于四个主要的原语构建，每个原语都作用于一个符号。

write: 创建一个新版本，仅包含传入的项目。
append: 创建一个新版本，包含附加到先前写入数据中的项目。
update: 创建一个新版本，包含使用提供的项目修补的先前数据。
read: 检索给定版本（如果未提供版本，则使用最新版本）。

这些原语并非包罗万象，但涵盖了大多数用例。我们将展示这些原语的用法。

写入数据¶

让我们从生成一些数据开始。下面的代码片段生成了一些带有日期时间索引的随机数据

import numpy as np
import pandas as pd
NUM_COLUMNS=10
NUM_ROWS=100_000
df = pd.DataFrame(np.random.randint(0,100,size=(NUM_ROWS, NUM_COLUMNS)), columns=[f"COL_{i}" for i in range(NUM_COLUMNS)], index=pd.date_range('2000', periods=NUM_ROWS, freq='h'))

让我们获取这些数据并将其写入 ArcticDB

>>> lib.write("my_data", df)
VersionedItem(symbol=my_data,library=test_fundamentals_1,data=<class 'NoneType'>,version=0,metadata=None,host=local)

读取数据¶

要读取数据，只需使用 read 原语

>>> data = lib.read("my_data")
>>> data
VersionedItem(symbol=my_data,library=test_fundamentals_1,data=<class 'pandas.core.frame.DataFrame'>,version=0,metadata=None,host=local)

注意，您将获得一个 VersionedItem - 它允许我们检索写入数据的版本

>>> data.version
0

由于这是对该符号的第一次写入，版本为 0。要检索数据

>>> data.data

切片和过滤¶

有关更多信息，请参阅入门指南。

修改数据¶

让我们附加一些数据。首先，请注意我们写入的数据结束于 2011 年

>>> data.data.tail()
                     COL_0  COL_1  COL_2  COL_3  COL_4  COL_5  COL_6  COL_7  COL_8  COL_9
2011-05-29 11:00:00     44     94     70     32     91      4     35     19     74     53
2011-05-29 12:00:00     79     51     67     48      8     83     46     54     86     38
2011-05-29 13:00:00     60     98     74      4     81     86     64     78     13     32
2011-05-29 14:00:00     27     24     16      6     84     99     11     94     29      4
2011-05-29 15:00:00     81     76     52     93     31     91     64      2     26     78

这仅仅是因为我们生成的数据始于 2000 年 1 月 1 日 00:00，包含 100,000 行，每小时增加一行。在 append 数据时，您附加的数据必须在现有数据结束之后开始。因此，让我们生成一些从 2012 年开始的数据

df_to_append = pd.DataFrame(np.random.randint(0,100,size=(NUM_ROWS, NUM_COLUMNS)), columns=[f"COL_{i}" for i in range(NUM_COLUMNS)], index=pd.date_range('2012', periods=NUM_ROWS, freq='h'))

现在开始附加！

>>> lib.append("my_data", df_to_append)
VersionedItem(symbol=my_data,library=test_fundamentals_1,data=<class 'NoneType'>,version=1,metadata=None,host=local)

append 创建了数据的新版本。读取版本 0 时，数据结束于 2011 年。读取版本 1 时，数据结束于 2023 年。

更新¶

如果 append 只能附加现有数据结束之后开始的数据，那么问题来了——我们如何修改数据呢？

答案是我们使用 update 原语。update 会用传入的数据覆盖（创建新版本 - 不会丢失任何东西！）现有的符号数据。请注意，现有数据中第一个和最后一个索引条目之间的整个范围将被传入的数据完全替换，并在需要时添加额外的索引条目。这意味着 update 是一个连续操作 - 有关更多信息，请参阅 update 的文档。

时间旅行！¶

ArcticDB 是双时间维度的 - 所有新版本都带有时间戳！让我们拉取数据的第一版，即在 append 之前的数据

>>> lib.read("my_date", as_of=0).data.tail()
                     COL_0  COL_1  COL_2  COL_3  COL_4  COL_5  COL_6  COL_7  COL_8  COL_9
2011-05-29 11:00:00     44     94     70     32     91      4     35     19     74     53
2011-05-29 12:00:00     79     51     67     48      8     83     46     54     86     38
2011-05-29 13:00:00     60     98     74      4     81     86     64     78     13     32
2011-05-29 14:00:00     27     24     16      6     84     99     11     94     29      4
2011-05-29 15:00:00     81     76     52     93     31     91     64      2     26     78

注意，它结束于 2011 年 - 就好像 append 从未发生过一样。as_of 也可以接受时间戳（datatime.datetime 或 pd.Timestamp）。