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

# 在 Amazon QLDB 中使用 PartiQL 查詢離子
<a name="ql-reference.query"></a>

**重要**  
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。

當您在 Amazon QLDB 中查詢資料時，您會以 PartiQL 格式撰寫陳述式，但 QLDB 會以 Amazon Ion 格式傳回結果。PartiQL 旨在與 SQL 相容，而 Ion 是 JSON 的延伸。這會導致您記錄查詢陳述式中資料與查詢結果顯示方式之間的語法差異。

本節說明使用 [QLDB 主控台](console_QLDB.md)或 [QLDB shell](data-shell.md) 手動執行 PartiQL 陳述式的基本語法和語意。

**提示**  
當您以程式設計方式執行 PartiQL 查詢時，最佳實務是使用參數化陳述式。您可以使用問號 (`?`) 做為陳述式中的繫結變數預留位置，以避免這些語法規則。這也更安全、更有效率。  
若要進一步了解，請參閱下列開始使用*驅動程式的*教學課程：  
Java： [快速入門教學課程](driver-quickstart-java.md) \$1 [技術指南參考](driver-cookbook-java.md)
.NET： [快速入門教學課程](driver-quickstart-dotnet.md) \$1 [技術指南參考](driver-cookbook-dotnet.md)
Go： [快速入門教學課程](driver-quickstart-golang.md) \$1 [技術指南參考](driver-cookbook-golang.md)
Node.js： [快速入門教學課程](driver-quickstart-nodejs.md) \$1 [技術指南參考](driver-cookbook-nodejs.md)
Python： [快速入門教學課程](driver-quickstart-python.md) \$1 [技術指南參考](driver-cookbook-python.md)

**Topics**
+ [語法和語意](#ql-reference.query.syntax)
+ [Backtick 表示法](#ql-reference.query.backtick)
+ [路徑導覽](#ql-reference.query.pathing)
+ [別名](#ql-reference.query.aliasing)
+ [PartiQL 規格](#ql-reference.query.spec)

## 語法和語意
<a name="ql-reference.query.syntax"></a>

使用 QLDB 主控台或 QLDB shell 查詢 Ion 資料時，下列是 PartiQL 的基本語法和語義：

**區分大小寫**  
所有 QLDB 系統物件名稱，包括欄位名稱、資料表名稱和分類帳名稱，都區分大小寫。

**字串值**  
在 Ion 中，雙引號 (`"..."`) 表示[字串](https://amzn.github.io/ion-docs/docs/spec.html#string)。  
在 PartiQL 中，單引號 (`'...'`) 表示字串。

**符號和識別符**  
在 Ion 中，單引號 (`'...'`) 表示 [符號](https://amzn.github.io/ion-docs/docs/spec.html#symbol)。Ion 中稱為*識別符*的符號子集以未引用的文字表示。  
在 PartiQL 中，雙引號 (`"..."`) 表示引用的 PartiQL 識別符，例如用作資料表名稱的[預留字詞](ql-reference.reserved.md)。未引用的文字代表一般的 PartiQL 識別符，例如不是預留單字的資料表名稱。

**離子常值**  
任何 Ion 常值都可以在 PartiQL 陳述式中以反引號 (``...``) 表示。

**欄位名稱**  
離子欄位名稱是區分大小寫的符號。PartiQL 可讓您在 DML 陳述式中以單引號表示欄位名稱。這是使用 PartiQL 的 `cast`函數定義符號的短期替代方案。它也比使用反引號來表示常值 Ion 符號更直覺。

### 文字
<a name="ql-reference.query.literals"></a>

PartiQL 查詢語言的字條對應至 Ion 資料類型，如下所示：

**純量**  
適用時請遵循 SQL 語法，如 [PartiQL-Ion 類型映射](ql-reference.docs.md#ql-reference.docs.types) 章節所述。例如：  
+ `5`
+ `'foo'`
+ `null`

**結構**  
也稱為許多格式和其他資料模型的元組或物件。  
以大括號 ( `{...}` ) 表示，並以逗號分隔`struct`元素。  
+ `{ 'id' : 3, 'arr': [1, 2] }`

**清單**  
也稱為陣列。  
以方括號表示 ( `[...]` )，清單元素以逗號分隔。  
+ `[ 1, 'foo' ]`

**包包**  
PartiQL 中的未排序集合。  
以雙角度括號表示 ( `<<...>>` )，包元素以逗號分隔。在 QLDB 中，資料表可視為包。不過，無法在資料表中的文件中巢狀包。  
+ `<< 1, 'foo' >>`

### 範例
<a name="ql-reference.query.example"></a>

以下是具有各種 Ion 類型的 `INSERT` 陳述式語法範例。

```
INSERT INTO VehicleRegistration VALUE
{
    'VIN' : 'KM8SRDHF6EU074761', --string
    'RegNum' : 1722, --integer
    'State' : 'WA',
    'City' : 'Kent',
    'PendingPenaltyTicketAmount' : 130.75, --decimal
    'Owners' : { --nested struct
        'PrimaryOwner' : { 'PersonId': '294jJ3YUoH1IEEm8GSabOs' },
        'SecondaryOwners' : [ --list of structs
            { 'PersonId' : '1nmeDdLo3AhGswBtyM1eYh' },
            { 'PersonId': 'IN7MvYtUjkp1GMZu0F6CG9' }
        ]
    },
    'ValidFromDate' : `2017-09-14T`, --Ion timestamp literal with day precision
    'ValidToDate' : `2020-06-25T`
}
```

## Backtick 表示法
<a name="ql-reference.query.backtick"></a>

PartiQL 完全涵蓋所有 Ion 資料類型，因此您可以撰寫任何陳述式而無需使用反引號。但在某些情況下，此 Ion 常值語法可以讓您的陳述式更清楚、更簡潔。

例如，若要插入具有 Ion 時間戳記和符號值的文件，您只能使用純 PartiQL 語法撰寫下列陳述式。

```
INSERT INTO myTable VALUE
{
    'myTimestamp': to_timestamp('2019-09-04T'),
    'mySymbol': cast('foo' as symbol)
}
```

這相當詳細，因此您可以使用反引號來簡化陳述式。

```
INSERT INTO myTable VALUE
{
    'myTimestamp': `2019-09-04T`,
    'mySymbol': `foo`
}
```

您也可以將整個結構括在反引號中，以節省一些額外的擊鍵動作。

```
INSERT INTO myTable VALUE
`{
    myTimestamp: 2019-09-04T,
    mySymbol: foo
}`
```

**重要**  
PartiQL 中的字串和符號是不同的類別。這表示即使他們有相同的文字，它們也不相等。例如，下列 PartiQL 表達式會評估為不同的 Ion 值。  

```
'foo'
```

```
`foo`
```

## 路徑導覽
<a name="ql-reference.query.pathing"></a>

撰寫資料處理語言 (DML) 或查詢陳述式時，您可以使用路徑步驟存取巢狀結構中的欄位。PartiQL 支援用於存取父系結構欄位名稱的點表示法。下列範例會存取父系 `Model`的欄位`Vehicle`。

```
Vehicle.Model
```

若要存取清單的特定元素，您可以使用方括號運算子來表示以零為基礎的順序數字。下列範例會存取 的 元素`SecondaryOwners`，其順序數為 `2`。換句話說，這是清單的第三個元素。

```
SecondaryOwners[2]
```

## 別名
<a name="ql-reference.query.aliasing"></a>

QLDB 支援開啟的內容和結構描述。因此，當您存取陳述式中的特定欄位時，確保取得預期結果的最佳方式是使用別名。例如，如果您未指定明確的別名，系統會為您的`FROM`來源產生隱含別名。

```
SELECT VIN FROM Vehicle
--is rewritten to
SELECT Vehicle.VIN FROM Vehicle AS Vehicle
```

但欄位名稱衝突的結果無法預測。如果名為 的另一個欄位`VIN`存在於文件中的巢狀結構中，則此查詢傳回`VIN`的值可能會讓您感到驚訝。最佳實務是改為撰寫下列陳述式。此查詢宣告`v`為跨越`Vehicle`資料表範圍的別名。`AS` 關鍵字為選用。

```
SELECT v.VIN FROM Vehicle [ AS ] v
```

在文件中進入巢狀集合時，別名特別有用。例如，下列陳述式宣告`o`為別名，其範圍超過集合 `VehicleRegistration.Owners`。

```
SELECT o.SecondaryOwners
FROM VehicleRegistration AS r, @r.Owners AS o
```

此`@`字元在技術上是選用的。但它明確表示您想要 內的`Owners`結構`VehicleRegistration`，而不是名為 的不同集合 `Owners`（如果有的話）。

## PartiQL 規格
<a name="ql-reference.query.spec"></a>

如需 PartiQL 查詢語言的詳細資訊，請參閱 [PartiQL 規格](https://partiql.org/assets/PartiQL-Specification.pdf)。