CREATE CUSTOM INDEX

Cassandra 5.0 是目前唯一支援的資料庫。

建立儲存附加索引 (SAI) 索引。您可以在同一個資料庫表格上建立多個次要索引，每個 SAI 索引都基於表格中的任一欄位。除了下列欄位資料類型之外，所有欄位資料類型都支援 SAI 索引

計數器
非凍結使用者定義類型 (UDT)

一個例外

當分割鍵僅包含一欄時，您無法根據分割鍵定義 SAI 索引。如果您嘗試在這種情況下建立 SAI 索引，SAI 會發出錯誤訊息。

但是，您可以在表格複合分割鍵中的其中一欄定義 SAI 索引，也就是由多個欄位組成的分割鍵。如果您需要根據其中一欄進行查詢，SAI 索引是一個有用的選項。事實上，您可以在需要時針對複合分割鍵中的每欄定義 SAI 索引。

根據資料庫表格中的任一欄定義一個或多個 SAI 索引（符合上述規則），隨後您可以執行高效能查詢，使用索引欄位來過濾結果。

請參閱 SAI 區段。

語法

BNF 定義

index_name::= re('[a-zA-Z_0-9]+')

CREATE CUSTOM INDEX [ IF NOT EXISTS ] [ <index_name> ]
  ON [ <keyspace_name>.]<table_name> (<column_name>)
    | [ (KEYS(<map_name>)) ]
    | [ (VALUES(<map_name>)) ]
    | [ (ENTRIES(<map_name>)) ]
  USING 'StorageAttachedIndex'
  [ WITH OPTIONS = { <option_map> } ] ;

語法圖例

圖例
語法慣例	說明
大寫	文字關鍵字。
小寫	非文字。
`< >`	變數值。替換為使用者定義的值。
`[]`	選用。方括號 (`[]`) 括住選用的命令引數。請勿輸入方括號。
`( )`	群組。圓括號 ( `( )` ) 識別要選擇的群組。請勿輸入圓括號。
`\|`	或。直線 (`\|`) 分隔備選元素。輸入任一元素。請勿輸入直線。
`...`	可重複。省略號 ( `...` ) 表示您可以根據需要重複語法元素。
`'<文字字串>'`	單引號 (`'`) 標記必須括住 CQL 陳述式中的文字字串。使用單引號保留大寫。
`{ <金鑰> : <值> }`	對應集合。大括號 (`{ }`) 括住對應集合或金鑰值對。冒號分隔金鑰和值。
`<資料類型2`	集合、清單、對應或組。尖括號 ( `< >` ) 括住集合、清單、對應或組中的資料類型。使用逗號分隔資料類型。
`<cql_statement>;`	結束 CQL 陳述式。分號 (`;`) 終止所有 CQL 陳述式。
`[--]`	使用兩個連字號 ( `--` ) 分隔命令列選項和命令引數。當引數可能被誤認為命令列選項時，此語法很有用。
`' <<schema\> ... </schema\>> '`	僅搜尋 CQL：單引號 (`'`) 括住整個 XML 架構宣告。
`@<xml_entity>='<xml_entity_type>'`	僅搜尋 CQL：識別實體和文字值以覆寫架構和 solrConfig 檔案中的 XML 元素。

index_name

索引的選用識別碼。如果未指定名稱，預設使用 <table_name>\_<column_name>\_idx。使用引號括住以使用特殊字元或保留大寫。

column_name

定義 SAI 索引的資料表欄位名稱。SAI 僅允許名稱中出現英數字元和底線。如果您嘗試定義包含其他字元的欄位名稱上的索引，SAI 會傳回 InvalidRequestException，而且不會建立索引。

map_name

與集合搭配使用，在 `CREATE TABLE` … `map(<map_name>)` 中指定的 `map_name` 識別碼。集合類型 `list` 和 `set` 適用一般欄位語法。

option_map

以 JSON 簡易格式定義選項。

選項說明

選項	說明
`case_sensitive`	比對字串值時忽略大小寫。預設值：`true`。
`normalize`	設為 `true` 時，對索引字串執行 Unicode 正規化。SAI 支援 Unicode 正規化形式 C (NFC)。設為 `true` 時，SAI 會將給定 Unicode 字元的不同版本正規化為單一版本，並保留索引中的所有標記和符號。例如，SAI 會將字元 Å (U+212B) 變更為 Å (U+00C5)。當實作將字串保留在正規化形式時，等價字串具有唯一的二進位表示。請參閱 Unicode 標準附錄 #15，Unicode 正規化形式。預設值：`false`。
`ascii`	設為 `true` 時，SAI 會將不在基本拉丁文 Unicode 區塊（前 127 個 ASCII 字元）中的字母、數字和符號字元轉換為 ASCII 等效字元（如果存在）。例如，此選項會將 à 變更為 a。預設值：`false`。
similarity_function	向量搜尋仰賴計算向量之間的相似度或距離來找出相關的相符項。相似度函數用於計算兩個向量之間的相似度。有效選項包括：EUCLIDEAN、DOT_PRODUCT、COSINE 預設值：`COSINE`

case_sensitive

比對字串值時忽略大小寫。預設值：`true`。

normalize

設為 `true` 時，對索引字串執行 Unicode 正規化。SAI 支援 Unicode 正規化形式 C (NFC)。設為 `true` 時，SAI 會將給定 Unicode 字元的不同版本正規化為單一版本，並保留索引中的所有標記和符號。例如，SAI 會將字元 Å (U+212B) 變更為 Å (U+00C5)。

當實作將字串保留在正規化形式時，等價字串具有唯一的二進位表示。請參閱 Unicode 標準附錄 #15，Unicode 正規化形式。

預設值：`false`。

ascii

設為 `true` 時，SAI 會將不在基本拉丁文 Unicode 區塊（前 127 個 ASCII 字元）中的字母、數字和符號字元轉換為 ASCII 等效字元（如果存在）。例如，此選項會將 à 變更為 a。預設值：`false`。

similarity_function

向量搜尋仰賴計算向量之間的相似度或距離來找出相關的相符項。相似度函數用於計算兩個向量之間的相似度。有效選項包括：EUCLIDEAN、DOT_PRODUCT、COSINE 預設值：`COSINE`

查詢運算子

SAI 支援針對具有 SAI 索引的表格使用下列查詢運算子

數字：`=、`<`、`>`、`⇐`、`>=`、`AND`、`OR`、`IN`
字串：`=、`CONTAINS`、`CONTAINS KEY`、`AND`、`OR`、`IN`

SAI 不支援針對具有 SAI 索引的表格使用下列查詢運算子

字串或數字：`LIKE`

範例

這些範例定義 `cycling.cyclist_semi_pro` 表格的 SAI 索引，此表格在 SAI 快速入門中示範。

CREATE INDEX lastname_sai_idx ON cycling.cyclist_semi_pro (lastname)
USING 'sai'
WITH OPTIONS = {'case_sensitive': 'false', 'normalize': 'true', 'ascii': 'true'};

CREATE INDEX age_sai_idx ON cycling.cyclist_semi_pro (age)
USING 'sai';

CREATE INDEX country_sai_idx ON cycling.cyclist_semi_pro (country)
USING 'sai'
WITH OPTIONS = {'case_sensitive': 'false', 'normalize': 'true', 'ascii': 'true'};

CREATE INDEX registration_sai_idx ON cycling.cyclist_semi_pro (registration)
USING 'sai';

有關透過這些範例 SAI 索引在 cycling.cyclist_semi_pro 中尋找資料的範例查詢，請參閱提交 CQL 查詢。另請參閱使用 SAI 進行查詢。

包含鍵、值和條目的 SAI 集合對應範例

下列範例示範在 SAI 索引中使用多種類型的集合對應（keys、values、entries）。有關相關資訊，請參閱建立集合和使用對應類型。

另請參閱本主題中類型為清單和集合的 SAI 集合範例。

首先，建立鍵集空間

CREATE KEYSPACE demo3 WITH REPLICATION =
       {'class': 'SimpleStrategy', 'replication_factor': '1'};

接著，使用鍵集空間

USE demo3;

建立一個 audit 表格，其中包含一個名為 text_map 的集合對應

CREATE TABLE audit ( id int PRIMARY KEY , text_map map<text, text>);

在同一個 map 欄位上建立多個 SAI 索引，每個索引都使用 KEYS、VALUES 和 ENTRIES。

CREATE CUSTOM INDEX ON audit (KEYS(text_map)) USING 'StorageAttachedIndex';
CREATE CUSTOM INDEX ON audit (VALUES(text_map)) USING 'StorageAttachedIndex';
CREATE CUSTOM INDEX ON audit (ENTRIES(text_map)) USING 'StorageAttachedIndex';

插入一些資料

INSERT INTO audit (id, text_map) values (1, {'Carlos':'Perotti', 'Marcel':'Silva'});
INSERT INTO audit (id, text_map) values (2, {'Giovani':'Pasi', 'Frances':'Giardello'});
INSERT INTO audit (id, text_map) values (3, {'Mark':'Pastore', 'Irene':'Cantona'});

查詢所有資料

查詢
結果

SELECT * FROM audit;

 id | text_map
----+---------------------------------------------
  1 | {'Carlos': 'Perotti', 'Marcel': 'Silva'}
  2 | {'Frances': 'Giardello', 'Giovani': 'Pasi'}
  3 | {'Irene': 'Cantona', 'Mark': 'Pastore'}

(3 rows)

使用 SAI 索引查詢 map 欄位中的特定條目

查詢
結果

SELECT * FROM audit WHERE text_map['Irene'] = 'Cantona' AND text_map['Mark'] = 'Pastore';

 id | text_map
----+-----------------------------------------
  3 | {'Irene': 'Cantona', 'Mark': 'Pastore'}

(1 rows)

使用 SAI 索引查詢 map 欄位中的特定鍵，並使用 CONTAINS KEY

查詢
結果

SELECT * FROM audit WHERE text_map CONTAINS KEY 'Giovani';

 id | text_map
----+---------------------------------------------
  2 | {'Frances': 'Giardello', 'Giovani': 'Pasi'}

(1 rows)

使用 SAI 索引查詢 map 欄位中的特定值，並使用 CONTAINS

查詢
結果

SELECT * FROM audit WHERE text_map CONTAINS 'Silva';

 id | text_map
----+------------------------------------------
  1 | {'Carlos': 'Perotti', 'Marcel': 'Silva'}

(1 rows)

請記住，在使用 SAI 索引的 CQL 查詢中，CONTAINS 子句受支援，且特定於

包含 keys、values 和 entries 的 SAI 集合對應
包含 list 和 set 類型的 SAI 集合

包含清單和集合類型的 SAI 集合範例

這些範例示範在 SAI 索引中使用 list 和 set 類型的集合。有關相關資訊，請參閱

如果您尚未建立鍵集空間，請建立鍵集空間。

CREATE KEYSPACE IF NOT EXISTS demo3 WITH REPLICATION =
       {'class': 'SimpleStrategy', 'replication_factor': '1'};

USE demo3;

使用清單類型

建立一個 calendar 表格，其中包含類型為 list 的集合。

CREATE TABLE calendar (key int PRIMARY KEY, years list<int>);

使用集合的 years 欄位建立一個 SAI 索引。

CREATE CUSTOM INDEX ON calendar(years) USING 'StorageAttachedIndex';

僅為示範目的，插入一些隨機的 int 清單資料作為 years。

請注意 INSERT 指令的方括號語法，用於清單值。

INSERT INTO calendar (key, years) VALUES (0, [1990,1996]);
INSERT INTO calendar (key, years) VALUES (1, [2000,2010]);
INSERT INTO calendar (key, years) VALUES (2, [2001,1990]);

使用 CONTAINS 範例進行查詢

查詢
結果

SELECT * FROM calendar WHERE years CONTAINS 1990;

 key | years
-----+--------------
   0 | [1990, 1996]
   2 | [2001, 1990]
(2 rows)

此範例使用 years list<int> 建立了 calendar 表格。當然，您可以使用 years list<text> 建立表格，例如，插入「字串」值，並針對字串進行查詢。

使用集合類型

現在，建立一個 calendar2 表格，其中包含類型為 set 的集合。

CREATE TABLE calendar2 (key int PRIMARY KEY, years set<int>);

使用集合的 years 欄位建立一個 SAI 索引，這次是針對 calendar2 表格。

CREATE CUSTOM INDEX ON calendar2(years) USING 'StorageAttachedIndex';

僅為示範目的，再次插入一些隨機的 int 集合資料作為 years。

注意 INSERT 命令用於設定值的捲曲大括號語法。

INSERT INTO calendar2 (key, years) VALUES (0, {1990,1996});
INSERT INTO calendar2 (key, years) VALUES (1, {2000,2010});
INSERT INTO calendar2 (key, years) VALUES (2, {2001,1990,2020});

查詢 CONTAINS 清單範例

查詢
結果

SELECT * FROM calendar2  WHERE years CONTAINS 1990;

 key | years
-----+--------------------
   0 |       {1990, 1996}
   2 | {1990, 2001, 2020}

(2 rows)