前提條件

• 已創建AccessKey，詳情請參見創建AccessKey。

• 已安裝Python環境。

• 授予賬號相應權限，詳情請參見授予RAM用戶權限。

安裝SDK

您可以通過pip安裝Python SDK，詳細說明請參見hologres-vector。

pip install hologres-vector

使用步驟

1. 輸入Hologres實例連接信息。

   from hologres_vector import HologresVector
   import os
   
   host = os.environ["<HOLO_HOST>"]
   port = os.environ["<HOLO_PORT>"]
   dbname = os.environ["<HOLO_DBNAME>"]
   user = os.environ["<HOLO_USER>"]
   password = os.environ["<HOLO_PASSWORD>"]
   
   connection_string = HologresVector.connection_string_from_db_params(host, port, dbname, user, password)

   參數說明如下：

   參數	描述
   HOLO_HOST	Hologres實例的網絡地址。 進入Hologres管理控制臺的實例詳情頁，從實例詳情頁獲取網絡地址。
   HOLO_PORT	Hologres的實例端口。 進入Hologres管理控制臺的實例詳情頁，從實例詳情頁獲取網絡地址。
   HOLO_DBNAME	Hologres創建的數據庫名稱。
   HOLO_USER	當前阿里云賬號的AccessKey ID。 您可以單擊AccessKey 管理，獲取AccessKey ID。
   HOLO_PASSWORD	當前阿里云賬號的AccessKey Secret。 您可以單擊AccessKey 管理，獲取AccessKey Secret。

2. 創建向量表。

   需要指定向量的維度，以及表中的除向量列、主鍵、JSON列以外的其他強Schema列及數據類型。

   table_name = "test_table"  # 定義表名
   holo = HologresVector(
       connection_string,     # 連接信息
       5,                     # 向量維度
       table_name=table_name, # 表名
       table_schema={"t": "text", "date": "timestamptz", "i": "int"},	#定義列及數據類型
       distance_method="SquaredEuclidean", # 距離函數，推薦用默認值，也可以選擇"Euclidean"或"InnerProduct"
     	pre_delete_table=True, # 若表已存在，是否刪表重建
   )

   table_schema：用于定義強Schema列及對應數據類型，在Hologres表中，table_schema下的每一個字段對應一個表的列。

3. 導入向量數據。

   通過Hologres Vector SDK進行向量數據導入時，會默認按512行進行攢批，以提升導入效率。

   # 數據示例
   vectors = [[0,0,0,0,0], [1,1,1,1,1], [2,2,2,2,2]]
   ids = ['0', '1', '2'] # primary key
   schema_datas = [
       {'t': 'text 0', 'date': '2023-08-02 18:30:00', 'i': 0},
       {'t': 'text 1', 'date': '2023-08-02 19:30:00', 'i': 1},
       {'t': 'text 2', 'date': '2023-08-02 20:30:00', 'i': 2},
   ]
   metadatas = [
       {'a': "hello"},
       {'b': 123},
       {},
   ]
   
   # 導入數據
   holo.upsert_vectors(vectors, ids, schema_datas=schema_datas, metadatas=metadatas)

   • vectors：向量列，用于存儲向量數據。

   • ids：主鍵，用于定義向量數據對應的主鍵ID。

   • metadatas：JSON列，用于將弱Schema字段、半結構化字段靈活定義到Hologres一個JSON列中。

4. 查詢向量數據。

   • 普通查詢：從數據庫中任取一條數據或定義filter條件查詢向量數據。

     # 任取一條數據
     holo.query(limit=1)
     # 返回結果
     [{'id': '2', 'vector': [2.0, 2.0, 2.0, 2.0, 2.0], 'metadata': {}}]
     
     # 通過filter條件查詢
     holo.query(schema_data_filters={'id': '1'})
     # 返回結果
     [{'id': '1', 'vector': [1.0, 1.0, 1.0, 1.0, 1.0], 'metadata': {'b': 123}}]

   • 近鄰查詢：根據給定向量從表中查詢最近鄰向量數據。

     # 查詢與給定向量最近鄰的top 2向量，并通過select_columns返回指定的列
     holo.search([0.1, 0.1, 0.1, 0.1, 0.1], k=2, select_columns=['t'])
     # 結果
     [{'id': '0', 'metadata': {'a': 'hello'}, 'distance': 0.05, 't': 'text 0'},
     {'id': '1', 'metadata': {'b': 123}, 'distance': 4.05, 't': 'text 1'}]

   • 融合查詢：根據給定向量從表中查詢最近鄰向量數據，并通過其他結構化字段定義過濾條件。

     # 查詢與給定向量最近鄰的top 2向量，并通過schema_data_filters定義過濾條件
     holo.search([0.1, 0.1, 0.1, 0.1, 0.1], k=2, schema_data_filters={'t': 'text 1'})
     # 結果
     [{'id': '1', 'metadata': {'b': 123}, 'distance': 4.05}]

其他操作

# 先插入一行id為3的數據
holo.upsert_vectors([[3, 3, 3, 3, 3]], [3], schema_datas=[{'t': 'old data'}])
# 再插入一行id為3的數據，下面這行會將上面的整行替換掉
holo.upsert_vectors([[-3, -3, -3, -3, -3]], [3], schema_datas=[{'t': 'new data'}])

# 查詢該行數據
holo.query(schema_data_filters={'id': '3'})
# 查詢結果
[{'id': '3', 'vector': [-3.0, -3.0, -3.0, -3.0, -3.0], 'metadata': {}}]