CREATE CUSTOM INDEX

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

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

計數器
地理空間類型：PointType、LineStringType、PolygonType
未凍結使用者定義類型 (UDT)

一個例外

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

但是，您可以在表格複合分割鍵中的其中一欄定義 SAI 索引，亦即由多欄組成的分割鍵。如果您需要根據其中一欄查詢，SAI 索引是一個有用的選項。事實上，您可以在複合分割鍵中的每一欄定義 SAI 索引（如果需要）。

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

請參閱 SAI 區段。

概要

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 'sai'
  [ WITH OPTIONS = { <option_map> } ] ;

語法範例

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

索引名稱

索引的選用識別碼。如果未指定名稱，則使用預設值 <表格名稱>_<欄位名稱>_idx。使用特殊字元或保留大寫時，請加上引號。

欄位名稱

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

對應名稱

與集合搭配使用時，在 CREATE TABLE 中指定的 map_name 識別碼… map(<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`。

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。

查詢運算子

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。

在 同一個欄位 上建立具有不同映射類型的多個 SAI 索引需要 Cassandra 5.0 或更新版本。

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

插入一些資料

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)

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

查詢
結果

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

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

(1 rows)

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

查詢
結果

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

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

(1 rows)

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

查詢
結果

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 集合

具有 list 和 set 類型的 SAI 集合範例

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

建立集合
使用 list 類型
使用 set 類型

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

USE demo3;

使用 list 類型

建立一個具有 list 類型的集合的 calendar 表格。

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

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

CREATE INDEX ON calendar(years) USING 'sai';

僅為示範目的，插入一些隨機的 int list 資料給 years。

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

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> 建立表格，例如，插入 'string' 值，並查詢字串。

使用 set 類型

現在使用 set 類型建立一個 calendar2 表格。

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

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

CREATE INDEX ON calendar2(years) USING 'sai';

僅為示範目的，再次插入一些隨機的 int set 資料給 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)