本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon Keyspaces 的 CQL 語言參考 （適用於 Apache Cassandra)
<a name="cql"></a>

連線至 Amazon Keyspaces 端點後，您可以使用 Cassandra 查詢語言 (CQL) 來使用資料庫。CQL 在許多方面與結構化查詢語言 (SQL) 類似。
+ **CQL 元素** – 本節涵蓋 Amazon Keyspaces 中支援的 CQL 基本元素，包括識別符、常數、術語和資料類型。它說明字串類型、數值類型、集合類型等概念。
+ **資料定義語言 (DDL)** – DDL 陳述式用於管理 Amazon Keyspaces 中的金鑰空間和資料表等資料結構。本節涵蓋建立、變更和捨棄金鑰空間和資料表，以及從point-in-time備份還原資料表的陳述式。
+ **資料處理語言 (DML) ** – DML 陳述式用於管理資料表中的資料。本節涵蓋選取、插入、更新和刪除資料的陳述式。它還說明了進階查詢功能，例如使用 `IN` 運算子、排序結果和分頁。
+ **內建函數** – Amazon Keyspaces 支援各種內建純量函數，可用於 CQL 陳述式。本節提供這些函數的概觀，包括其用量的範例。

在本主題中，您會找到在 Amazon Keyspaces 中有效使用 CQL 的詳細語法、範例和最佳實務。

**Topics**
+ [Amazon Keyspaces 中的 Cassandra 查詢語言 (CQL) 元素](cql.elements.md)
+ [Amazon Keyspaces 中的 DDL 陳述式 （資料定義語言）](cql.ddl.md)
+ [Amazon Keyspaces 中的 DML 陳述式 （資料處理語言）](cql.dml.md)
+ [Amazon Keyspaces 中的內建函數](cql.functions.md)

# Amazon Keyspaces 中的 Cassandra 查詢語言 (CQL) 元素
<a name="cql.elements"></a>

了解 Amazon Keyspaces 支援的 Cassandra 查詢語言 (CQL) 元素，包括識別符、常數、術語和資料類型。

**Topics**
+ [identifier](#cql.elements.identifier)
+ [constants](#cql.elements.constants)
+ [term](#cql.elements.term)
+ [資料類型](#cql.data-types)
+ [Amazon Keyspaces 資料類型的 JSON 編碼](#cql.data-types.JSON)

## 識別碼
<a name="cql.elements.identifier"></a>

識別符 （或名稱） 用於識別資料表、資料欄和其他物件。可以引用或不引用識別符。下列適用。

```
identifier          ::=  unquoted_identifier | quoted_identifier
unquoted_identifier ::=  re('[a-zA-Z][a-zA-Z0-9_]*')
quoted_identifier   ::=  '"' (any character where " can appear if doubled)+ '"'
```

## 常數
<a name="cql.elements.constants"></a>

已定義下列常數。

```
constant ::=  string | integer | float | boolean | uuid | blob | NULL
string   ::=  '\'' (any character where ' can appear if doubled)+ '\''
              '$$' (any character other than '$$') '$$'
integer  ::=  re('-?[0-9]+')
float    ::=  re('-?[0-9]+(\.[0-9]*)?([eE][+-]?[0-9+])?') | NAN | INFINITY
boolean  ::=  TRUE | FALSE
uuid     ::=  hex{8}-hex{4}-hex{4}-hex{4}-hex{12}
hex      ::=  re("[0-9a-fA-F]")
blob     ::=  '0' ('x' | 'X') hex+
```

## 條款
<a name="cql.elements.term"></a>

一詞表示支援的 值類型。術語定義如下。

```
term                 ::=  constant | literal | function_call | arithmetic_operation | type_hint | bind_marker
literal              ::=  collection_literal | tuple_literal
function_call        ::=  identifier '(' [ term (',' term)* ] ')'
arithmetic_operation ::=  '-' term | term ('+' | '-' | '*' | '/' | '%') term
```

## 資料類型
<a name="cql.data-types"></a>

Amazon Keyspaces 支援下列資料類型：

### 字串類型
<a name="cql.data-types.string"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `ascii`  | 代表 ASCII 字元字串。 | 
|  `text`  | 代表 UTF-8 編碼字串。 | 
|  `varchar`  |  代表 UTF-8 編碼字串 (`varchar` 是 的別名`text`)。  | 

### 數值類型
<a name="cql.data-types.numeric"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `bigint`  | 代表 64 位元簽署長。 | 
|  `counter`  | 代表 64 位元帶正負號的整數計數器。如需詳細資訊，請參閱[計數器](#cql.data-types.numeric.counters)。 | 
|  `decimal`  | 代表變數精確度小數位數。 | 
|  `double`  | 代表 64 位元 IEEE 754 浮點。 | 
|  `float`  | 代表 32 位元 IEEE 754 浮點。 | 
|  `int`  |  代表 32 位元帶正負號的整數。  | 
|  `varint`  |  代表 \$1/-10^38 範圍內的整數值。  | 

#### 計數器
<a name="cql.data-types.numeric.counters"></a>

資料`counter`欄包含 64 位元帶正負號的整數。計數器值會使用 [UPDATE](cql.dml.update.md)陳述式遞增或遞減，且無法直接設定。這可讓`counter`資料欄有助於追蹤計數。例如，您可以使用計數器來追蹤日誌檔案中的項目數量，或在社交網路上檢視文章的次數。下列限制適用於資料`counter`欄：
+ 類型 的資料欄`counter`不能是資料表`primary key`的一部分。
+ 在包含一或多個 類型資料欄的資料表中`counter`，該資料表中的所有資料欄都必須是 類型`counter`。

如果計數器更新失敗 （例如，由於逾時或失去與 Amazon Keyspaces 的連線），用戶端不知道計數器值是否已更新。如果重試更新，對計數器值的更新可能會再次套用。

### Blob 類型
<a name="cql.data-types.blob"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `blob`  | 代表任意位元組。 | 

### 布林值 (Boolean) 類型
<a name="cql.data-types.boolean"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `boolean`  | 代表 true或 false。 | 

### 時間相關類型
<a name="cql.data-types.time"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `date`  | 格式為 的字串<yyyy>-<mm>-<dd>。 | 
|  `timestamp`  | 64 位元帶正負號整數，代表自 epoch 起的日期和時間 (1970 年 1 月 1 日，格林威治標準時間 00：00：00)，以毫秒為單位。 | 
|  `timeuuid`  | 代表[版本 1 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address))。 | 

### 集合類型
<a name="cql.data-types.collection"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `list`  | 代表常值元素的排序集合。 | 
|  `map`  | 代表索引鍵/值對的未排序集合。 | 
|  `set`  | 代表一或多個常值元素的未排序集合。 | 

您可以在角括號中使用集合類型後接另一個資料類型 （例如， `TEXT`或 `INT`) 來宣告集合資料欄。您可以使用 `SET`的 建立資料欄`TEXT`，也可以建立 `MAP` `TEXT`和 `INT`鍵值對的 ，如下列範例所示。

```
SET <TEXT>
MAP <TEXT, INT>
```

*非凍結*集合可讓您更新每個個別集合元素。儲存個別元素的用戶端時間戳記和存留時間 (TTL) 設定。

當您在集合類型上使用 `FROZEN`關鍵字時，集合的值會序列化為單一不可變的值，Amazon Keyspaces 會將它們視為 `BLOB`。這是*凍結*集合。`INSERT` 或 `UPDATE`陳述式會覆寫整個凍結集合。您無法更新凍結集合中的個別元素。

用戶端時間戳記和存留時間 (TTL) 設定會套用至整個凍結集合，而不是個別元素。`Frozen`集合資料欄可以是資料表`PRIMARY KEY`的一部分。

您可以巢狀凍結集合。例如，`SET`如果 `MAP` 使用 `FROZEN`關鍵字，您可以在 `MAP`中定義 ，如下列範例所示。

```
SET <FROZEN> <MAP <TEXT, INT>>>
```

Amazon Keyspaces 預設支援最多 8 個層級的凍結集合巢狀化。如需詳細資訊，請參閱[Amazon Keyspaces 服務配額](quotas.md#table)。如需 Apache Cassandra 功能差異的詳細資訊，請參閱 [`FROZEN` 集合](functional-differences.md#functional-differences.frozen-collections)。如需 CQL 語法的詳細資訊，請參閱 [CREATE TABLE](cql.ddl.table.md#cql.ddl.table.create)和 [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter)。

### 雙組類型
<a name="cql.data-types.tuple"></a>

`tuple` 資料類型代表常值元素的邊界群組。您可以使用元組做為 的替代方案`user defined type`。您不需要針對元組使用 `FROZEN`關鍵字。這是因為元組一律凍結，您無法個別更新元素。

### 其他類型
<a name="cql.data-types.other"></a>


****  

| 資料類型 | Description | 
| --- | --- | 
|  `inet`  | 代表 IP 地址的字串，採用 IPv4 或 IPv6 格式。 | 

### 靜態
<a name="cql.data-types.static"></a>

在具有叢集資料欄的 Amazon Keyspaces 資料表中，您可以使用 `STATIC`關鍵字來建立任何類型的靜態資料欄。

下列陳述式為範例。

```
my_column INT STATIC
```

如需使用靜態資料欄的詳細資訊，請參閱 [預估 Amazon Keyspaces 中靜態資料欄的容量耗用](static-columns.md)。

### 使用者定義的類型 (UDTs)
<a name="cql.data-types.user-defined"></a>

Amazon Keyspaces 支援使用者定義的類型 (UDTs)。您可以使用任何有效的 Amazon Keyspaces 資料類型來建立 UDT，包括集合和其他現有的 UDTs。您可以在金鑰空間中建立 UDTs，並使用它們來定義金鑰空間中任何資料表中的資料欄。

如需 CQL 語法的詳細資訊，請參閱 [使用者定義的類型 (UDTs)](cql.ddl.type.md)。如需使用 UDTs的詳細資訊，請參閱 [Amazon Keyspaces 中使用者定義的類型 (UDT)](udts.md)。

若要檢閱每個金鑰空間支援的 UDTs 數量、支援的巢狀層級，以及其他與 UDTs 相關的預設值和配額，請參閱 [Amazon Keyspaces 中使用者定義類型 (UDTs) 的配額和預設值](quotas.md#quotas-udts)。

## Amazon Keyspaces 資料類型的 JSON 編碼
<a name="cql.data-types.JSON"></a>

Amazon Keyspaces 提供與 Apache Cassandra 相同的 JSON 資料類型映射。下表說明 Amazon Keyspaces 在`INSERT JSON`陳述式中接受的資料類型，以及 Amazon Keyspaces 使用`SELECT JSON`陳述式傳回資料時使用的資料類型。

對於 `float`、、 `int``UUID`和 等單一欄位資料類型`date`，您也可以將資料插入為 `string`。對於複合資料類型和集合，例如 `tuple`、 `map`和 `list`，您也可以將資料插入為 JSON 或編碼的 `JSON string`。


****  

| JSON 資料類型 | `INSERT JSON` 陳述式中接受的資料類型 | `SELECT JSON` 陳述式中傳回的資料類型 | 備註 | 
| --- | --- | --- | --- | 
|  `ascii`  | string | string | 使用 JSON 字元逸出 `\u`。 | 
|  `bigint`  | integer, string | integer | 字串必須是有效的 64 位元整數。 | 
|  `blob`  | string | string | 字串應以 開頭，`0x`後面接著偶數的十六進位數字。 | 
|  `boolean`  | boolean, string | boolean | 字串必須是 `true`或 `false`。 | 
|  `date`  | string | string | 日期格式為 `YYYY-MM-DD`，時區 UTC。 | 
|  `decimal`  | integer, float, string | float | 在用戶端解碼器中，可以超過 32 位元或 64 位元 IEEE-754 浮點精確度。 | 
|  `double`  | integer, float, string | float | 字串必須是有效的整數或浮點數。 | 
|  `float`  | integer, float, string | float | 字串必須是有效的整數或浮點數。 | 
|  `inet`  | string | string | IPv4 或 IPv6 地址。 | 
|  `int`  | integer, string | integer | 字串必須是有效的 32 位元整數。 | 
|  `list`  | list, string | list | 使用原生 JSON 清單表示法。 | 
|  `map`  | map, string | map | 使用原生 JSON 映射表示法。 | 
|  `smallint`  | integer, string | integer | 字串必須是有效的 16 位元整數。 | 
|  `set`  | list, string | list | 使用原生 JSON 清單表示法。 | 
|  `text`  | string | string | 使用 JSON 字元逸出 `\u`。 | 
|  `time`  | string | string | 一天中的時間，格式為 `HH-MM-SS[.fffffffff]`。 | 
|  `timestamp`  | integer, string | string | 時間戳記。字串常數可讓您將時間戳記儲存為日期。`YYYY-MM-DD HH:MM:SS.SSS` 傳回格式為 的日期戳記。 | 
|  `timeuuid`  | string | string | 輸入 1 UUID。如需 UUID 格式[constants](#cql.elements.constants)，請參閱 。 | 
|  `tinyint`  | integer, string | integer | 字串必須是有效的 8 位元整數。 | 
|  `tuple`  | list, string | list | 使用原生 JSON 清單表示法。 | 
|  `UDT`  | map, string | map | 使用原生 JSON 映射表示法搭配欄位名稱做為索引鍵。 | 
|  `uuid`  | string | string | 如需 UUID 格式[constants](#cql.elements.constants)，請參閱 。 | 
|  `varchar`  | string | string | 使用 JSON 字元逸出 `\u`。 | 
|  `varint`  | integer, string | integer | 可變長度； 可能會溢出用戶端解碼器中的 32 位元或 64 位元整數。 | 

# Amazon Keyspaces 中的 DDL 陳述式 （資料定義語言）
<a name="cql.ddl"></a>

*資料定義語言* (DDL) 是一組 Cassandra 查詢語言 (CQL) 陳述式，用於管理 Amazon Keyspaces （適用於 Apache Cassandra) 中的資料結構，例如金鑰空間和資料表。您可以使用 DDL 建立這些資料結構、在建立後修改它們，並在它們不再使用時將其移除。Amazon Keyspaces 會以非同步方式執行 DDL 操作。如需如何確認非同步操作已完成的詳細資訊，請參閱 [非同步建立和刪除金鑰空間和資料表](functional-differences.md#functional-differences.table-keyspace-management)。

 支援下列 DDL 陳述式：
+  [建立 KEYSPACE](cql.ddl.keyspace.md#cql.ddl.keyspace.create) 
+  [ALTER KEYSPACE](cql.ddl.keyspace.md#cql.ddl.keyspace.alter) 
+  [DROP KEYSPACE](cql.ddl.keyspace.md#cql.ddl.keyspace.drop) 
+  [使用](cql.ddl.keyspace.md#cql.ddl.keyspace.use) 
+  [建立資料表](cql.ddl.table.md#cql.ddl.table.create) 
+  [ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter) 
+  [RESTORE 資料表](cql.ddl.table.md#cql.ddl.table.restore) 
+  [DROP 資料表](cql.ddl.table.md#cql.ddl.table.drop) 
+  [建立類型](cql.ddl.type.md#cql.ddl.type.create) 
+  [DROP 類型](cql.ddl.type.md#cql.ddl.type.drop) 

**Topics**
+ [Keyspaces](cql.ddl.keyspace.md)
+ [表格](cql.ddl.table.md)
+ [使用者定義的類型 (UDTs)](cql.ddl.type.md)

# Keyspaces
<a name="cql.ddl.keyspace"></a>

與一或多個應用程式相關的*鍵空間*群組相關資料表。在關聯式資料庫管理系統 (RDBMS) 方面，金鑰空間大致類似於資料庫、資料表空間或類似建構。

**注意**  
在 Apache Cassandra 中，金鑰空間會決定如何在多個儲存節點之間複寫資料。不過，Amazon Keyspaces 是一項全受管服務：其儲存層的詳細資訊會代表您管理。因此，Amazon Keyspaces 中的鍵空間僅為邏輯建構，與基礎實體儲存無關。

如需 Amazon Keyspaces 金鑰空間配額限制和限制的相關資訊，請參閱 [Amazon Keyspaces 配額 （適用於 Apache Cassandra)](quotas.md)。

**Topics**
+ [建立 KEYSPACE](#cql.ddl.keyspace.create)
+ [ALTER KEYSPACE](#cql.ddl.keyspace.alter)
+ [DROP KEYSPACE](#cql.ddl.keyspace.drop)
+ [USE](#cql.ddl.keyspace.use)

## 建立 KEYSPACE
<a name="cql.ddl.keyspace.create"></a>

使用 `CREATE KEYSPACE`陳述式建立新的金鑰空間。

**語法**

```
create_keyspace_statement ::= 
    CREATE KEYSPACE [ IF NOT EXISTS ] keyspace_name
    WITH options
```

其中：
+ `keyspace_name` 是要建立的金鑰空間名稱。
+ *選項*是下列一或多個項目：
  + `REPLICATION` – 表示金鑰空間複寫策略的映射：
    + `SingleRegionStrategy` – 適用於單一區域金鑰空間。(必要)
    + `NetworkTopologyStrategy` – 指定至少兩個 AWS 區域。每個區域的複寫係數為 3。(選用)
  + `DURABLE_WRITES` – 寫入 Amazon Keyspaces 一律耐用，因此不需要此選項。不過，如果指定，則值必須為 `true`。
  + `TAGS` – 建立時要附加至資源的鍵/值對標籤清單。(選用)

**範例**

建立金鑰空間，如下所示。

```
CREATE KEYSPACE my_keyspace
    WITH REPLICATION = {'class': 'SingleRegionStrategy'} and TAGS ={'key1':'val1', 'key2':'val2'} ;
```

若要建立多區域金鑰空間，請指定`NetworkTopologyStrategy`並包含至少兩個 AWS 區域。每個區域的複寫係數為 3。

```
CREATE KEYSPACE my_keyspace
    WITH REPLICATION = {'class':'NetworkTopologyStrategy', 'us-east-1':'3', 'ap-southeast-1':'3','eu-west-1':'3'};
```

## ALTER KEYSPACE
<a name="cql.ddl.keyspace.alter"></a>

您可以使用下列*選項*的 `ALTER KEYSPACE WITH`陳述式
+ `REPLICATION` – 使用此選項將新 AWS 區域 複本新增至金鑰空間。您可以將新區域新增至單一區域或多區域金鑰空間。
+ `TAGS` – 使用此選項從鍵空間新增或移除標籤。

**語法**

```
alter_keyspace_statement ::= 
    ALTER KEYSPACE keyspace_name
    WITH options
```

其中：
+ `keyspace_name` 是要變更的金鑰空間名稱。
+ *選項*為下列其中一項：
  + `ADD | DROP TAGS` – 要從鍵空間新增或移除的鍵值對標籤清單。
  + `REPLICATION` – 表示金鑰空間複寫策略的映射；
    + `class`– 將金鑰空間`NetworkTopologyStrategy`定義為多區域金鑰空間。
    + `region`– AWS 區域 為此金鑰空間指定一個額外的 。每個區域的複寫係數為 3。
    + `CLIENT_SIDE_TIMESTAMPS` – 預設值為 `DISABLED`。您只能將狀態變更為 `ENABLED`。

**範例**

修改金鑰空間，如下列範例所示，以新增標籤。

```
ALTER KEYSPACE my_keyspace ADD TAGS {'key1':'val1', 'key2':'val2'};
```

若要將第三個區域新增至多區域金鑰空間，您可以使用下列陳述式。

```
ALTER KEYSPACE my_keyspace
WITH REPLICATION = {
    'class': 'NetworkTopologyStrategy',
    'us-east-1': '3',
    'us-west-2': '3',
    'us-west-1': '3'
} AND CLIENT_SIDE_TIMESTAMPS = {'status': 'ENABLED'};
```

## DROP KEYSPACE
<a name="cql.ddl.keyspace.drop"></a>

使用 `DROP KEYSPACE`陳述式移除金鑰空間，包括其所有內容，例如資料表。

**語法**

```
drop_keyspace_statement ::= 
    DROP KEYSPACE [ IF EXISTS ] keyspace_name
```

其中：
+ *keyspace\$1name* 是要捨棄的金鑰空間名稱。

**範例**

```
DROP KEYSPACE my_keyspace;
```

## USE
<a name="cql.ddl.keyspace.use"></a>

使用 `USE`陳述式來定義目前的金鑰空間。這可讓您參考繫結至特定金鑰空間的物件，例如資料表和類型，而無需使用包含金鑰空間字首的完整名稱。

**語法**

```
use_statement ::= 
    USE keyspace_name
```

其中：
+ *keyspace\$1name* 是要使用的金鑰空間名稱。

**範例**

```
USE my_keyspace;
```

# 表格
<a name="cql.ddl.table"></a>

*資料表*是 Amazon Keyspaces 中的主要資料結構。資料表中的資料會組織成資料列和資料欄。這些資料欄的子集用於透過分割區索引鍵的規格來判斷分割區 （最終是資料置放）。

另一組資料欄可以定義成叢集資料欄，這表示它們可以參與做為查詢執行的述詞。

根據預設，會使用*隨需*輸送量容量建立新的資料表。您可以變更新資料表和現有資料表的容量模式。如需讀取/寫入容量輸送量模式的詳細資訊，請參閱 [在 Amazon Keyspaces 中設定讀取/寫入容量模式](ReadWriteCapacityMode.md)。

對於佈建模式中的資料表，您可以設定選用的 `AUTOSCALING_SETTINGS`。如需 Amazon Keyspaces 自動擴展和可用選項的詳細資訊，請參閱 [在現有資料表上設定自動擴展](autoscaling.configureTable.md)。

如需 Amazon Keyspaces 資料表配額限制和限制的相關資訊，請參閱 [Amazon Keyspaces 配額 （適用於 Apache Cassandra)](quotas.md)。

**Topics**
+ [CREATE TABLE](#cql.ddl.table.create)
+ [ALTER TABLE](#cql.ddl.table.alter)
+ [RESTORE 資料表](#cql.ddl.table.restore)
+ [DROP TABLE](#cql.ddl.table.drop)

## CREATE TABLE
<a name="cql.ddl.table.create"></a>

使用 `CREATE TABLE`陳述式建立新的資料表。

 **語法**

```
create_table_statement ::=  CREATE TABLE [ IF NOT EXISTS ] table_name
    '('
        column_definition 
        ( ',' column_definition )*
        [ ',' PRIMARY KEY '(' primary_key ')' ]
    ')' [ WITH table_options ]

column_definition      ::=  column_name cql_type [ FROZEN ][ STATIC ][ PRIMARY KEY]

primary_key            ::=  partition_key [ ',' clustering_columns ]

partition_key          ::=  column_name
                              | '(' column_name ( ',' column_name )* ')'

clustering_columns     ::=  column_name ( ',' column_name )*

table_options          ::=  [table_options]
                              | CLUSTERING ORDER BY '(' clustering_order ')' [ AND table_options ]
                              | cdc
                              | CUSTOM_PROPERTIES
                              | AUTOSCALING_SETTINGS
                              | default_time_to_live
                              | TAGS

clustering_order       ::=  column_name (ASC | DESC) ( ',' column_name (ASC | DESC) )*
```

其中：
+ `table_name` 是要建立的資料表名稱。完整名稱包含金鑰空間字首。或者，您可以使用 金鑰空間陳述式來設定目前的`USE`金鑰空間。
+ `column_definition` 包含下列項目：
  +  *`column_name`* – 資料欄的名稱。
  + `cql_type` – Amazon Keyspaces 資料類型 （請參閱 [資料類型](cql.elements.md#cql.data-types))。
  + `FROZEN` – 將使用者定義或類型 `collection`（例如 `LIST`、 `SET`或 `MAP`) 的此欄指定為凍結。*凍結*集合會序列化為單一不可變值，並視為 `BLOB`。如需詳細資訊，請參閱[集合類型](cql.elements.md#cql.data-types.collection)。
  + `STATIC` – 將此欄指定為靜態。靜態資料欄會存放相同分割區中所有資料列共用的值。
  + `PRIMARY KEY` – 將此欄指定為資料表的主索引鍵。
+ `primary_key` 包含下列項目：
  + `partition_key`
  + `clustering_columns`
+ `partition_key`:
  + 分割區索引鍵可以是單一資料欄，也可以是由兩個或多個資料欄組成的複合值。主索引鍵的分割區索引鍵部分是必要的，並決定 Amazon Keyspaces 如何存放您的資料。
+ `clustering_columns`:
  + 主索引鍵的選用叢集資料欄部分會決定如何在每個分割區中叢集和排序資料。
+ `table_options` 包含下列項目：
  + *`CLUSTERING ORDER BY`* – 資料表上的預設 CLUSTERING ORDER 由 `ASC`（遞增） 排序方向的叢集索引鍵組成。指定它來覆寫預設排序行為。
  +  *`cdc`* – 布林值，指定 Amazon Keyspaces 是否為資料表建立變更資料擷取 (CDC) 串流。預設值為 `false`。若要在啟用串流`view type`時指定 ，`cdc_specification`請使用 設定 `CUSTOM_PROPERTIES` 。
  +  *`CUSTOM_PROPERTIES`* – Amazon Keyspaces 特有的設定映射。
    +  `capacity_mode`：指定資料表的讀取/寫入輸送量容量模式。選項包括 `throughput_mode:PAY_PER_REQUEST` 和 `throughput_mode:PROVISIONED`. 佈建的容量模式需要 `read_capacity_units`和 `write_capacity_units`做為輸入。預設值為 `throughput_mode:PAY_PER_REQUEST`。
    +  `cdc_specification`：指定 CDC 串流`view_type`的 。選項為：
      + `NEW_AND_OLD_IMAGES` – 變更前後的兩個資料列版本。這是預設值。
      + `NEW_IMAGE` – 變更後的列版本。
      + `OLD_IMAGE` – 變更前的資料列版本。
      + `KEYS_ONLY` – 已變更資料列的分割區和叢集索引鍵。

      如需 CDC 串流的詳細資訊，請參閱 [在 Amazon Keyspaces 中使用變更資料擷取 (CDC) 串流](cdc.md)。如需程式碼範例，請參閱 [在 Amazon Keyspaces 中建立新資料表時啟用 CDC 串流](keyspaces-enable-cdc-new-table.md)。
    +  `client_side_timestamps`：指定資料表的用戶端時間戳記是啟用或停用。選項包括 `{'status': 'enabled'}` 和 `{'status': 'disabled'}`. 如果未指定，則預設值為 `status:disabled`。為資料表啟用用戶端時間戳記後，就無法停用此設定。
    +  `encryption_specification`：指定靜態加密的加密選項。如果未指定，則預設值為 `encryption_type:AWS_OWNED_KMS_KEY`。加密選項客戶受管金鑰需要 Amazon Resource Name (ARN) 格式的 AWS KMS 金鑰做為輸入：`kms_key_identifier:ARN`：`kms_key_identifier:ARN`。
    +  `point_in_time_recovery`：指定資料表的point-in-time還原是啟用或停用。選項包括 `status:enabled` 和 `status:disabled`. 如果未指定，則預設值為 `status:disabled`。
    + `replica_updates`：指定 專屬的多區域資料表設定 AWS 區域。對於多區域資料表，您可以為每個 以不同的方式設定資料表的讀取容量 AWS 區域。您可以設定下列參數來執行此操作。如需詳細資訊和範例，請參閱 [在 Amazon Keyspaces 中使用自動擴展的佈建模式中建立多區域資料表](tables-mrr-create-provisioned.md)。
      + `region` – 具有下列設定的資料表複本 AWS 區域 的 ：
        + `read_capacity_units`
    +  `TTL`：啟用資料表的存留時間自訂設定。若要啟用，請使用 `status:enabled`。預設值為 `status:disabled`。`TTL` 啟用 之後，您就無法為資料表停用它。
  + `AUTOSCALING_SETTINGS` 包含下列佈建模式中資料表的選用設定。如需詳細資訊和範例，請參閱 [使用自動擴展建立新的資料表](autoscaling.createTable.md)。
    + `provisioned_write_capacity_autoscaling_update`:
      + `autoscaling_disabled` – 若要啟用寫入容量的自動擴展，請將 值設定為 `false`。預設值為 `true`。(選用)
      + `minimum_units` – 資料表應隨時準備好支援的最小寫入輸送量層級。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
      + `maximum_units` – 資料表應隨時準備好支援的寫入輸送量上限。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
      + `scaling_policy` – Amazon Keyspaces 支援目標追蹤政策。自動擴展目標是資料表的佈建寫入容量。
        + `target_tracking_scaling_policy_configuration` – 若要定義目標追蹤政策，您必須定義目標值。如需目標追蹤和冷卻時間的詳細資訊，請參閱《*Application Auto Scaling * [ Scaling 使用者指南》中的目標追蹤擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html)。
          + `target_value` – 資料表的目標使用率。Amazon Keyspaces 自動擴展可確保耗用容量與佈建容量的比率保持在或接近此值。您能以百分比的形式定義 `target_value`。介於 20 到 90 之間的兩倍。(必要)
          + `scale_in_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
          + `scale_out_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個橫向擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
          + `disable_scale_in`：`boolean`指定資料表`scale-in`是否已停用或已啟用的 。此參數預設為停用。若要開啟 `scale-in`，請將 `boolean`值設定為 `FALSE`。這表示會自動為您縮減資料表的容量。(選用) 
    + `provisioned_read_capacity_autoscaling_update`:
      + `autoscaling_disabled` – 若要啟用讀取容量的自動擴展，請將 值設定為 `false`。預設值為 `true`。(選用)
      + `minimum_units` – 資料表應隨時準備好支援的輸送量最低層級。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
      + `maximum_units` – 資料表應隨時準備好支援的輸送量上限。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
      + `scaling_policy` – Amazon Keyspaces 支援目標追蹤政策。自動擴展目標是資料表的佈建讀取容量。
        + `target_tracking_scaling_policy_configuration` – 若要定義目標追蹤政策，您必須定義目標值。如需目標追蹤和冷卻期間的詳細資訊，請參閱《*Application Auto Scaling * [ Scaling 使用者指南》中的目標追蹤擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html)。
          + `target_value` – 資料表的目標使用率。Amazon Keyspaces 自動擴展可確保耗用容量與佈建容量的比率保持在或接近此值。您能以百分比的形式定義 `target_value`。介於 20 到 90 之間的兩倍。(必要)
          + `scale_in_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
          + `scale_out_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個橫向擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
          + `disable_scale_in`：`boolean`指定資料表`scale-in`是否已停用或已啟用的 。此參數預設為停用。若要開啟 `scale-in`，請將 `boolean`值設定為 `FALSE`。這表示會自動為您縮減資料表的容量。(選用) 
    + `replica_updates`：指定多區域資料表 AWS 區域 的特定自動擴展設定。對於多區域資料表，您可以為每個 以不同的方式設定資料表的讀取容量 AWS 區域。您可以設定下列參數來執行此操作。如需詳細資訊和範例，請參閱 [更新 Amazon Keyspaces 中多區域資料表的佈建容量和自動擴展設定](tables-mrr-autoscaling.md)。
      + `region` – 具有下列設定的資料表複本 AWS 區域 的 ：
        + `provisioned_read_capacity_autoscaling_update`
          + `autoscaling_disabled` – 若要啟用資料表讀取容量的自動擴展，請將 值設定為 `false`。預設值為 `true`。(選用) 
**注意**  
必須為資料表的所有複本啟用或停用多區域資料表的自動擴展。
          + `minimum_units` – 資料表應隨時準備好支援的讀取輸送量最低層級。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
          + `maximum_units` – 資料表應隨時準備好支援的讀取輸送量上限。此值必須介於 1 和您帳戶的每秒最大輸送量配額之間 （預設為 40，000)。
          + `scaling_policy` – Amazon Keyspaces 支援目標追蹤政策。自動擴展目標是資料表的佈建讀取容量。
            + `target_tracking_scaling_policy_configuration` – 若要定義目標追蹤政策，您必須定義目標值。如需目標追蹤和冷卻時間的詳細資訊，請參閱《*Application Auto Scaling * [ Scaling 使用者指南》中的目標追蹤擴展政策](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html)。
              + `target_value` – 資料表的目標使用率。Amazon Keyspaces 自動擴展可確保耗用讀取容量與佈建讀取容量的比率保持在或接近此值。您能以百分比的形式定義 `target_value`。介於 20 到 90 之間的兩倍。(必要)
              + `scale_in_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
              + `scale_out_cooldown` – 擴展活動之間的冷卻時間，以秒為單位，可讓資料表在另一個橫向擴展活動開始之前穩定。如果未提供任何值，則預設值為 0。(選用)
              + `disable_scale_in`：`boolean`指定資料表`scale-in`是否已停用或已啟用的 。此參數預設為停用。若要開啟 `scale-in`，請將 `boolean`值設定為 `FALSE`。這表示系統會自動為您縮減資料表的讀取容量。(選用) 
  + `default_time_to_live` – 資料表的預設存留時間設定，以秒為單位。
  + `TAGS` – 建立索引鍵/值對標籤時要附加至資源的清單。
  + `clustering_order` 包含下列項目：
    +  *`column_name`* – 資料欄的名稱。
    +  *`ASC | DESC`* – 設定上階 (`ASC`) 或下階 (`DESC`) 順序修改器。如果未指定，預設順序為 ASC。

**範例**

```
CREATE TABLE IF NOT EXISTS my_keyspace.my_table (
                                            id text,
                                            name text,
                                            region text,
                                            division text,
                                            project text,
                                            role text,
                                            pay_scale int,
                                            vacation_hrs float,
                                            manager_id text,
                                            PRIMARY KEY (id,division))
                                            WITH CUSTOM_PROPERTIES={
                                                'capacity_mode':{
                                                        'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20
                                                    },
                                                'point_in_time_recovery':{'status': 'enabled'},
                                                'encryption_specification':{
                                                        'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                                                        'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'
                                                    }
                                            }
                                            AND CLUSTERING ORDER BY (division ASC) 
                                            AND TAGS={'key1':'val1', 'key2':'val2'}
                                            AND default_time_to_live = 3024000;
```

在使用叢集資料欄的資料表中，非叢集資料欄可以在資料表定義中宣告為靜態資料欄。如需靜態資料欄的詳細資訊，請參閱 [預估 Amazon Keyspaces 中靜態資料欄的容量耗用](static-columns.md)。

**範例**

```
CREATE TABLE my_keyspace.my_table (
                                            id int,
                                            name text,
                                            region text,
                                            division text,
                                            project text STATIC,
                                            PRIMARY KEY (id,division));
```

您可以使用使用者定義類型 (UDT) 的欄來建立資料表。範例中的第一個陳述式會建立 類型，第二個陳述式會使用 類型的資料欄來建立資料表。

**範例**

```
CREATE TYPE my_keyspace."udt""N@ME" (my_field int);
CREATE TABLE my_keyspace.my_table (my_col1 int pri key, my_col2 "udt""N@ME");
```

## ALTER TABLE
<a name="cql.ddl.table.alter"></a>

使用 `ALTER TABLE`陳述式來新增資料欄、新增標籤或變更資料表的自訂屬性。

**語法**

```
alter_table_statement ::=  ALTER TABLE table_name    
 
        [ ADD ( column_definition | column_definition_list)  ] 
        [[ADD | DROP] TAGS {'key1':'val1', 'key2':'val2'}]            
        [ WITH table_options [ , ... ] ] ;
        
column_definition      ::=  column_name cql_type
```

其中：
+ `table_name` 是要修改的資料表名稱。
+ `column_definition` 是要新增的資料欄名稱和資料類型。
+ `column_definition_list` 是放在括號內以逗號分隔的資料欄清單。
+ `table_options` 包含下列項目：
  + `AUTOSCALING_SETTINGS` 包含佈建資料表的選用自動擴展設定。如需語法和詳細說明，請參閱 [CREATE TABLE](#cql.ddl.table.create)。如需範例，請參閱 [在現有資料表上設定自動擴展](autoscaling.configureTable.md)。
  +  *`cdc`* – 布林值，指定 Amazon Keyspaces 是否為資料表建立變更資料擷取 (CDC) 串流。預設值為 `false`。若要在啟用串流`view type`時指定 ，`cdc_specification`請使用 設定 `CUSTOM_PROPERTIES` 。
  +  *`CUSTOM_PROPERTIES`* – Amazon Keyspaces 特有的設定映射。
    +  `capacity_mode`：指定資料表的讀取/寫入輸送量容量模式。選項包括 `throughput_mode:PAY_PER_REQUEST` 和 `throughput_mode:PROVISIONED`. 佈建的容量模式需要 `read_capacity_units`和 `write_capacity_units`做為輸入。預設值為 `throughput_mode:PAY_PER_REQUEST`。
    +  `cdc_specification`：指定 CDC 串流`view_type`的 。選項為：
      + `NEW_AND_OLD_IMAGES` – 變更前後的兩個資料列版本。這是預設值。
      + `NEW_IMAGE` – 變更後的列版本。
      + `OLD_IMAGE` – 變更前的資料列版本。
      + `KEYS_ONLY` – 已變更資料列的分割區和叢集索引鍵。

      如需 CDC 串流的詳細資訊，請參閱 [在 Amazon Keyspaces 中使用變更資料擷取 (CDC) 串流](cdc.md)。如需程式碼範例，請參閱 [為 Amazon Keyspaces 中的現有資料表啟用 CDC 串流](keyspaces-enable-cdc-alter-table.md)。
    +  `client_side_timestamps`：指定資料表的用戶端時間戳記是啟用或停用。選項包括 `{'status': 'enabled'}` 和 `{'status': 'disabled'}`. 如果未指定，則預設值為 `status:disabled`。為資料表啟用用戶端時間戳記後，就無法停用此設定。
    +  `encryption_specification`：指定靜態加密的加密選項。選項包括 `encryption_type:AWS_OWNED_KMS_KEY` 和 `encryption_type:CUSTOMER_MANAGED_KMS_KEY`. 加密選項客戶受管金鑰需要 Amazon Resource Name (ARN) 格式的 AWS KMS 金鑰做為輸入：`kms_key_identifier:ARN`。
    +  `point_in_time_recovery`：指定資料表的point-in-time還原是啟用或停用。選項包括 `status:enabled` 和 `status:disabled`. 預設值為 `status:disabled`。
    + `replica_updates`：指定多區域資料表 AWS 區域 的特定設定。對於多區域資料表，您可以為每個資料表設定不同的讀取容量 AWS 區域。您可以設定下列參數來執行此操作。如需詳細資訊和範例，請參閱 [更新 Amazon Keyspaces 中多區域資料表的佈建容量和自動擴展設定](tables-mrr-autoscaling.md)。
      + `region` – 具有下列設定的資料表複本 AWS 區域 的 ：
        + `read_capacity_units` 
    +  `ttl`：啟用資料表的存留時間自訂設定。若要啟用，請使用 `status:enabled`。預設值為 `status:disabled`。`ttl`啟用 之後，您就無法為資料表停用它。
+ `default_time_to_live`：資料表的預設存留時間設定，以秒為單位。
+ `TAGS` 是要連接到資源的鍵/值對標籤清單。

**注意**  
使用 ALTER TABLE，您只能變更單一自訂屬性。您不能在同一陳述式中結合多個 ALTER TABLE 命令。

**範例**

下列陳述式說明如何將資料欄新增至現有資料表。

```
ALTER TABLE mykeyspace.mytable ADD (ID int);
```

此陳述式說明如何將兩個集合資料欄新增至現有資料表：
+ 包含巢狀凍結集合`col_frozen_list`的凍結集合欄
+ `col_map` 包含巢狀凍結集合的非凍結集合欄

```
ALTER TABLE my_Table ADD(col_frozen_list FROZEN<LIST<FROZEN<SET<TEXT>>>>, col_map MAP<INT, FROZEN<SET<INT>>>);
```

下列範例示範如何將使用使用者定義類型 (UDT) 的資料欄新增至資料表。

```
ALTER TABLE my_keyspace.my_table ADD (my_column, my_udt;);
```

若要變更資料表的容量模式並指定讀取和寫入容量單位，您可以使用下列陳述式。

```
ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20}};
```

下列陳述式指定資料表的客戶受管 KMS 金鑰。

```
ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={     
              'encryption_specification':{ 
                      'encryption_type': 'CUSTOMER_MANAGED_KMS_KEY', 
                      'kms_key_identifier':'arn:aws:kms:eu-west-1:5555555555555:key/11111111-1111-111-1111-111111111111'     
                  } 
         };
```

若要啟用資料表的point-in-time還原，您可以使用下列陳述式。

```
ALTER TABLE mykeyspace.mytable WITH CUSTOM_PROPERTIES={'point_in_time_recovery': {'status': 'enabled'}};
```

若要設定資料表的預設存留時間值，以秒為單位，您可以使用下列陳述式。

```
ALTER TABLE my_table WITH default_time_to_live = 2592000;
```

此陳述式會啟用資料表的自訂存留時間設定。

```
ALTER TABLE mytable WITH CUSTOM_PROPERTIES={'ttl':{'status': 'enabled'}};
```

## RESTORE 資料表
<a name="cql.ddl.table.restore"></a>

使用 `RESTORE TABLE`陳述式將資料表還原至某個時間點。此陳述式需要在point-in-time復原。如需詳細資訊，請參閱[使用 point-in-time復原來備份和還原資料](PointInTimeRecovery.md)。

**語法**

```
restore_table_statement ::=  
    RESTORE TABLE restored_table_name FROM TABLE source_table_name 
                    [ WITH table_options [ , ... ] ];
```

其中：
+ `restored_table_name` 是還原資料表的名稱。
+ `source_table_name` 是來源資料表的名稱。
+ `table_options` 包含下列項目：
  + `restore_timestamp` 是 ISO 8601 格式的還原點時間。如果未指定，則會使用目前的時間戳記。
  +  *`CUSTOM_PROPERTIES`* – Amazon Keyspaces 特有的設定映射。
    +  `capacity_mode`：指定資料表的讀取/寫入輸送量容量模式。選項包括 `throughput_mode:PAY_PER_REQUEST` 和 `throughput_mode:PROVISIONED`. 佈建的容量模式需要 `read_capacity_units`和 `write_capacity_units`做為輸入。預設值是來源資料表的目前設定。
    +  `encryption_specification`：指定靜態加密的加密選項。選項包括 `encryption_type:AWS_OWNED_KMS_KEY` 和 `encryption_type:CUSTOMER_MANAGED_KMS_KEY`. 加密選項客戶受管金鑰需要 Amazon Resource Name (ARN) 格式的 AWS KMS 金鑰做為輸入：`kms_key_identifier:ARN`。若要將以客戶受管金鑰加密的資料表還原至以 加密的資料表 AWS 擁有的金鑰，Amazon Keyspaces 需要存取來源資料表的 AWS KMS 金鑰。
    +  `point_in_time_recovery`：指定資料表的point-in-time還原是啟用或停用。選項包括 `status:enabled` 和 `status:disabled`. 與建立新資料表時不同，還原資料表的預設狀態是 ，`status:enabled`因為設定繼承自來源資料表。若要停用還原資料表的 PITR，您必須`status:disabled`明確設定 。
    + `replica_updates`：指定多區域資料表 AWS 區域 的特定設定。對於多區域資料表，您可以為每個資料表設定不同的讀取容量 AWS 區域。您可以設定下列參數來執行此操作。
      + `region` – 具有下列設定的資料表複本 AWS 區域 的 ：
        + `read_capacity_units` 
  + `AUTOSCALING_SETTINGS` 包含佈建資料表的選用自動擴展設定。如需詳細的語法和說明，請參閱 [CREATE TABLE](#cql.ddl.table.create)。
  + `TAGS` 是要連接到資源的鍵/值對標籤清單。

**注意**  
刪除的資料表只能還原至刪除時間。

**範例**

```
RESTORE TABLE mykeyspace.mytable_restored from table mykeyspace.my_table 
WITH restore_timestamp = '2020-06-30T04:05:00+0000'
AND custom_properties = {'point_in_time_recovery':{'status':'disabled'}, 'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 10, 'write_capacity_units': 20}}
AND TAGS={'key1':'val1', 'key2':'val2'};
```

## DROP TABLE
<a name="cql.ddl.table.drop"></a>

使用 `DROP TABLE`陳述式從 金鑰空間移除資料表。

**語法**

```
drop_table_statement ::=  
    DROP TABLE [ IF EXISTS ] table_name
```

其中：
+ `IF EXISTS` 如果資料表不存在， `DROP TABLE`會防止 失敗。(選用)
+ `table_name` 是要捨棄的資料表名稱。

**範例**

```
DROP TABLE my_keyspace.my_table;
```

# 使用者定義的類型 (UDTs)
<a name="cql.ddl.type"></a>

*UDT* – 欄位和資料類型的分組，可用於在 Amazon Keyspaces 中定義單一資料欄。UDTs 的有效資料類型都是支援的 Cassandra 資料類型，包括您已在相同金鑰空間中建立的集合和其他 UDTs。如需支援的 Cassandra 資料類型的詳細資訊，請參閱 [Cassandra 資料類型支援](cassandra-apis.md#cassandra-data-type)。

```
user_defined_type::= udt_name
udt_name::= [ keyspace_name '.' ] identifier
```

**Topics**
+ [CREATE TYPE](#cql.ddl.type.create)
+ [DROP TYPE](#cql.ddl.type.drop)

## CREATE TYPE
<a name="cql.ddl.type.create"></a>

使用 `CREATE TYPE`陳述式來建立新的類型。

 **語法**

```
create_type_statement ::=  CREATE TYPE [ IF NOT EXISTS ] udt_name
    '('field_definition ( ',' field_definition)* ')'
            field_definition::= identifier cql_type
```

其中：
+ `IF NOT EXISTS` 如果類型已存在， 會`CREATE TYPE`防止 失敗。(選用)
+ `udt_name` 是類型格式 UDT 的完整名稱，例如 `my_keyspace.my_type`。如果您使用 `USE`陳述式定義目前的金鑰空間，則不需要指定金鑰空間名稱。
+ `field_definition` 包含名稱和類型。

下表顯示允許的 UDT 名稱範例。第一欄顯示如何在建立 類型時輸入名稱，第二欄顯示 Amazon Keyspaces 如何在內部格式化名稱。Amazon Keyspaces 預期 等操作的格式化名稱`GetType`。


| 輸入的名稱 | 格式化名稱 | 注意 | 
| --- | --- | --- | 
|  MY\$1UDT  | my\$1udt | 如果沒有雙引號，Amazon Keyspaces 會將所有大寫字元轉換為小寫。 | 
|  "MY\$1UDT"  | MY\$1UDT | 使用雙引號時，Amazon Keyspaces 會遵守大寫字元，並從格式化名稱中移除雙引號。 | 
|  "1234"  | 1234 | 使用雙引號時，名稱可以以數字開頭，Amazon Keyspaces 會從格式化的名稱中移除雙引號。 | 
|  "Special\$1Ch@r@cters<>\$1\$1"  | Special\$1Ch@r@cters<>\$1\$1 | 使用雙引號時，名稱可以包含特殊字元，Amazon Keyspaces 會從格式化的名稱中移除雙引號。 | 
|  "nested""""""quotes"  | nested"""quotes | Amazon Keyspaces 會從格式化名稱中移除外部雙引號和逸出雙引號。 | 

**範例**

```
CREATE TYPE my_keyspace.phone (
    country_code int,
    number text
);
```

如果巢狀 UDTs 凍結，您可以巢狀 UDT。如需 類型預設值和配額的詳細資訊，請參閱 [Amazon Keyspaces UDT 配額和預設值](quotas.md#udt-table)。

```
CREATE TYPE my_keyspace.user (
    first_name text,
    last_name text,
    phones FROZEN<phone>
);
```

如需示範如何建立 UDTs更多程式碼範例，請參閱 [Amazon Keyspaces 中使用者定義的類型 (UDT)](udts.md)。

## DROP TYPE
<a name="cql.ddl.type.drop"></a>

使用 `DROP TYPE`陳述式刪除 UDT。您只能刪除其他類型或資料表未使用的類型。

 **語法**

```
drop_type_statement ::=  DROP TYPE [ IF EXISTS ] udt_name
```

其中：
+ `IF EXISTS` 如果類型不存在， 會`DROP TYPE`防止 失敗。(選用)
+ `udt_name` 是類型格式 UDT 的完整名稱，例如 `my_keyspace.my_type`。如果您使用 `USE`陳述式定義目前的金鑰空間，則不需要指定金鑰空間名稱。

**範例**

```
DROP TYPE udt_name;
```

# Amazon Keyspaces 中的 DML 陳述式 （資料處理語言）
<a name="cql.dml"></a>

*資料處理語言* (DML) 是一組 Cassandra 查詢語言 (CQL) 陳述式，用於管理 Amazon Keyspaces （適用於 Apache Cassandra) 資料表中的資料。您可使用 DML 陳述式新增、修改或刪除資料表中的資料。

您也可以使用 DML 陳述式來查詢資料表中的資料。（請注意，CQL 不支援聯結或子查詢。)

**Topics**
+ [SELECT](cql.dml.select.md)
+ [INSERT](cql.dml.insert.md)
+ [UPDATE](cql.dml.update.md)
+ [DELETE](cql.dml.delete.md)

# SELECT
<a name="cql.dml.select"></a>

使用 SELECT 陳述式查詢資料。

**語法**

```
select_statement ::=  SELECT  [ JSON ] ( select_clause | '*' )
                      FROM table_name
                      [ WHERE 'where_clause' ]
                      [ ORDER BY 'ordering_clause' ]
                      [ LIMIT (integer | bind_marker) ]
                      [ ALLOW FILTERING ]
select_clause    ::=  selector [ AS identifier ] ( ',' selector [ AS identifier ] )
selector         ::=  column_name
                      | term
                      | CAST '(' selector AS cql_type ')'
                      | function_name '(' [ selector ( ',' selector )* ] ')'
where_clause     ::=  relation ( AND relation )*
relation         ::=  column_name operator term
                      TOKEN
operator         ::=  '=' | '<' | '>' | '<=' | '>=' | IN | CONTAINS | CONTAINS KEY
ordering_clause  ::=  column_name [ ASC | DESC ] ( ',' column_name [ ASC | DESC ] )*
```

**範例**

```
SELECT name, id, manager_id FROM "myGSGKeyspace".employees_tbl ;

SELECT JSON name, id, manager_id FROM "myGSGKeyspace".employees_tbl ;
```

如需將 JSON 編碼資料類型映射至 Amazon Keyspaces 資料類型的資料表，請參閱 [Amazon Keyspaces 資料類型的 JSON 編碼](cql.elements.md#cql.data-types.JSON)。

**使用 `IN`關鍵字**

`IN` 關鍵字指定一或多個值的相等性。它可以套用至分割區索引鍵和叢集資料欄。結果會依索引鍵在`SELECT`陳述式中呈現的順序傳回。

**範例**

```
SELECT * from mykeyspace.mytable WHERE primary.key1 IN (1,2) and clustering.key1 = 2;
SELECT * from mykeyspace.mytable WHERE primary.key1 IN (1,2) and clustering.key1 <= 2;
SELECT * from mykeyspace.mytable WHERE primary.key1 = 1 and clustering.key1 IN (1, 2);
SELECT * from mykeyspace.mytable WHERE primary.key1 <= 2 and clustering.key1 IN (1, 2) ALLOW FILTERING;
```

如需`IN`關鍵字以及 Amazon Keyspaces 如何處理陳述式的詳細資訊，請參閱 [在 Amazon Keyspaces 的查詢中使用 `IN`運算子搭配 `SELECT`陳述式](in.select.md)。

**排序結果**

`ORDER BY` 子句指定傳回結果的排序順序。它需要資料欄名稱清單以及每個資料欄的排序順序做為引數。您只能依子句順序指定叢集資料欄。不允許使用非叢集資料欄。排序順序選項`ASC`適用於遞增和`DESC`遞減排序。如果省略排序順序，則會使用叢集資料欄的預設順序。如需可能的排序順序，請參閱 [在 Amazon Keyspaces `ORDER BY`中使用 排序結果](ordering-results.md)。

**範例**

```
SELECT name, id, division, manager_id FROM "myGSGKeyspace".employees_tbl WHERE id = '012-34-5678' ORDER BY division;
```

`ORDER BY` 搭配 `IN`關鍵字使用 時，結果會在頁面中排序。不支援使用已停用分頁進行完整重新排序。

**TOKEN**

您可以將`TOKEN`函數套用至 `SELECT`和 `WHERE`子句中的資料`PARTITION KEY`欄。使用 `TOKEN`函數時，Amazon Keyspaces 會根據 的映射字符值傳回資料列，`PARTITION_KEY`而不是根據 的值傳回資料列`PARTITION KEY`。

`TOKEN` `IN`關鍵字不支援關聯。

**範例**

```
SELECT TOKEN(id) from my_table; 

SELECT TOKEN(id) from my_table WHERE TOKEN(id) > 100 and TOKEN(id) < 10000;
```

**TTL 函數**

您可以使用 `TTL`函數搭配 `SELECT`陳述式，以秒為單位擷取為資料欄存放的過期時間。如果未設定`TTL`任何值，函數會傳回 `null`。

**範例**

```
SELECT TTL(my_column) from my_table;
```

`TTL` 函數無法用於多儲存格資料欄，例如集合。

**WRITETIME 函式**

只有在資料表使用用戶端時間戳記時，您才能使用 `WRITETIME`函數搭配 `SELECT`陳述式來擷取存放為資料欄值中繼資料的時間戳記。如需詳細資訊，請參閱[Amazon Keyspaces 中的用戶端時間戳記](client-side-timestamps.md)。

```
SELECT WRITETIME(my_column) from my_table;
```

`WRITETIME` 函數無法用於多儲存格資料欄，例如集合。

**注意**  
為了相容於已建立的 Cassandra 驅動程式行為，當您透過 Cassandra 驅動程式和開發人員工具使用 Cassandra 查詢語言 (CQL) API 呼叫對系統資料表執行操作時，不會強制執行標籤型授權政策。如需詳細資訊，請參閱[根據標籤的 Amazon Keyspaces 資源存取](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-tags)。

# INSERT
<a name="cql.dml.insert"></a>

使用 `INSERT`陳述式將資料列新增至資料表。

**語法**

```
insert_statement ::=  INSERT INTO table_name ( names_values | json_clause )
                      [ IF NOT EXISTS ]
                      [ USING update_parameter ( AND update_parameter )* ]
names_values     ::=  names VALUES tuple_literal
json_clause      ::=  JSON string [ DEFAULT ( NULL | UNSET ) ]                
names            ::=  '(' column_name ( ',' column_name )* ')'
```

**範例**

```
INSERT INTO "myGSGKeyspace".employees_tbl (id, name, project, region, division, role, pay_scale, vacation_hrs, manager_id)
VALUES ('012-34-5678','Russ','NightFlight','US','Engineering','IC',3,12.5, '234-56-7890') ;
```

**更新參數**

`INSERT` 支援下列值做為 `update_parameter`：
+ `TTL` – 以秒為單位的時間值。最大可設定的值為 630,720,000 秒，相當於 20 年。
+ `TIMESTAMP` – 代表自稱為 的標準基準時間以來微秒數`bigint`的值epoch：1970 年 1 月 1 日 00：00：00 GMT。Amazon Keyspaces 中的時間戳記必須介於過去 2 天到未來的 5 分鐘之間。

**範例**

```
INSERT INTO my_table (userid, time, subject, body, user)
        VALUES (B79CB3BA-745E-5D9A-8903-4A02327A7E09, 96a29100-5e25-11ec-90d7-b5d91eceda0a, 'Message', 'Hello','205.212.123.123')
        USING TTL 259200;
```

**JSON 支援**

如需將 JSON 編碼資料類型映射至 Amazon Keyspaces 資料類型的資料表，請參閱 [Amazon Keyspaces 資料類型的 JSON 編碼](cql.elements.md#cql.data-types.JSON)。

您可以使用 `JSON`關鍵字，將 `JSON`編碼的映射插入為單一資料列。對於資料表中存在但 JSON 插入陳述式中省略的資料欄，請使用 `DEFAULT UNSET`保留現有的值。使用 `DEFAULT NULL`將 NULL 值寫入省略的資料欄的每一列，並覆寫現有的值 （需支付標準寫入費用）。 `DEFAULT NULL`是預設選項。

**範例**

```
INSERT INTO "myGSGKeyspace".employees_tbl JSON '{"id":"012-34-5678",
                                                 "name": "Russ",
                                                 "project": "NightFlight",
                                                 "region": "US",
                                                 "division": "Engineering",
                                                 "role": "IC",
                                                 "pay_scale": 3,
                                                 "vacation_hrs": 12.5,
                                                 "manager_id": "234-56-7890"}';
```

如果 JSON 資料包含重複的金鑰，Amazon Keyspaces 會儲存金鑰的最後一個值 （類似於 Apache Cassandra)。在下列範例中，如果重複的金鑰是 `id`，`234-56-7890`則會使用 值。

**範例**

```
INSERT INTO "myGSGKeyspace".employees_tbl JSON '{"id":"012-34-5678",
                                                 "name": "Russ",
                                                 "project": "NightFlight",
                                                 "region": "US",
                                                 "division": "Engineering",
                                                 "role": "IC",
                                                 "pay_scale": 3,
                                                 "vacation_hrs": 12.5,
                                                 "id": "234-56-7890"}';
```

# UPDATE
<a name="cql.dml.update"></a>

使用 `UPDATE`陳述式來修改資料表中的資料列。

**語法**

```
update_statement ::=  UPDATE table_name
                      [ USING update_parameter ( AND update_parameter )* ]
                      SET assignment ( ',' assignment )*
                      WHERE where_clause
                      [ IF ( EXISTS | condition ( AND condition )*) ]
update_parameter ::=  ( integer | bind_marker )
assignment       ::=  simple_selection '=' term
                     | column_name '=' column_name ( '+' | '-' ) term
                     | column_name '=' list_literal '+' column_name
simple_selection ::=  column_name
                     | column_name '[' term ']'
                     | column_name '.' `field_name
condition        ::=  simple_selection operator term
```

**範例**

```
UPDATE "myGSGKeyspace".employees_tbl SET pay_scale = 5 WHERE id = '567-89-0123' AND division = 'Marketing' ;
```

若要遞增 `counter`，請使用下列語法。如需詳細資訊，請參閱[計數器](cql.elements.md#cql.data-types.numeric.counters)。

```
UPDATE ActiveUsers SET counter = counter + 1  WHERE user = A70FE1C0-5408-4AE3-BE34-8733E5K09F14 AND action = 'click';
```

**更新參數**

`UPDATE` 支援下列值做為 `update_parameter`：
+ `TTL` – 以秒為單位的時間值。最大可設定的值為 630,720,000 秒，相當於 20 年。
+ `TIMESTAMP` – 代表自稱為 的標準基準時間以來微秒數`bigint`的值epoch：1970 年 1 月 1 日 00：00：00 GMT。Amazon Keyspaces 中的時間戳記必須介於過去 2 天到未來的 5 分鐘之間。

**範例**

```
UPDATE my_table (userid, time, subject, body, user)
        VALUES (B79CB3BA-745E-5D9A-8903-4A02327A7E09, 96a29100-5e25-11ec-90d7-b5d91eceda0a, 'Message', 'Hello again','205.212.123.123')
        USING TIMESTAMP '2022-11-03 13:30:54+0400';
```

# DELETE
<a name="cql.dml.delete"></a>

使用 `DELETE`陳述式從資料表中移除資料列。

**語法**

```
delete_statement ::=  DELETE [ simple_selection ( ',' simple_selection ) ]
                      FROM table_name
                      [ USING update_parameter ( AND update_parameter )* ]
                      WHERE where_clause
                      [ IF ( EXISTS | condition ( AND condition )*) ]

simple_selection ::=  column_name
                     | column_name '[' term ']'
                     | column_name '.' `field_name

condition        ::=  simple_selection operator term
```

其中：
+ `table_name` 是包含您要刪除之資料列的資料表。

**範例**

```
DELETE manager_id FROM "myGSGKeyspace".employees_tbl WHERE id='789-01-2345' AND division='Executive' ;
```

`DELETE` 支援以下值為 `update_parameter`：
+ `TIMESTAMP` – 代表自稱為 的標準基準時間以來微秒數`bigint`的值epoch：1970 年 1 月 1 日 00：00：00 GMT。

# Amazon Keyspaces 中的內建函數
<a name="cql.functions"></a>

Amazon Keyspaces （適用於 Apache Cassandra) 支援可在 Cassandra 查詢語言 (CQL) 陳述式中使用的各種內建函數。

**Topics**
+ [純量函數](#cql.functions.scalar)

## 純量函數
<a name="cql.functions.scalar"></a>

*純量函數*會對單一值執行計算，並將結果傳回為單一值。Amazon Keyspaces 支援下列純量函數。


****  

| 函式 | Description | 
| --- | --- | 
|  `blobAsType`  | 傳回指定資料類型的值。 | 
|  `cast`  | 將一種原生資料類型轉換為另一種原生資料類型。 | 
|  `currentDate`  | 傳回目前日期/時間做為日期。 | 
|  `currentTime`  | 以時間的形式傳回目前的日期/時間。 | 
|  `currentTimestamp`  | 以時間戳記的形式傳回目前的日期/時間。 | 
|  `currentTimeUUID`  | 以 傳回目前的日期/時間timeuuid。 | 
|  `fromJson`  | 將 JSON 字串轉換為所選資料欄的資料類型。 | 
|  `maxTimeuuid`  | 傳回時間戳記或日期字串的最大可能timeuuid值。 | 
|  `minTimeuuid`  | 傳回時間戳記或日期字串的最小timeuuid可能。 | 
|  `now`  | 傳回新的唯一 timeuuid。 | 
|  `toDate`  | 將 timeuuid或時間戳記轉換為日期類型。 | 
|  `toJson`  | 以 JSON 格式傳回所選資料欄的資料欄值。 | 
|  `token`  | 傳回分割區索引鍵的雜湊值。 | 
|  `toTimestamp`  | 將 timeuuid或 日期轉換為時間戳記。 | 
|  `TTL`  | 傳回資料欄的過期時間，以秒為單位。 | 
|  `typeAsBlob`  | 將指定的資料類型轉換為 blob。 | 
|  `toUnixTimestamp`  | 將 timeuuid或時間戳記轉換為 bigInt。 | 
|  `uuid`  | 傳回隨機第 4 版 UUID。 | 
|  `writetime`  | 傳回指定資料欄值的時間戳記。 | 
|  `dateOf`  | （已棄用） 擷取 的時間戳記timeuuid，並將值傳回為日期。 | 
|  `unixTimestampOf`  | （已棄用） 擷取 的時間戳記timeuuid，並以原始的 64 位元整數時間戳記傳回值。 |