本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 舊版 DynamoDB 條件式參數 本文件提供 DynamoDB 中舊版條件式參數的概觀，並建議改用新的表達式參數。其涵蓋 AttributesToGet、AttributeUpdates、ConditionalOperator、Expected、KeyConditions、QueryFilter 和 ScanFilter 等參數的詳細資訊，並提供如何使用新表達式參數取代的範例。 **重要** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 此外，DynamoDB 不允許在單一呼叫中混用舊式條件式參數和表達式參數。例如，使用 `AttributesToGet` 和 `ConditionExpression` 來呼叫 `Query` 操作會導致錯誤。 下表顯示仍支援這些舊版參數的 DynamoDB API 操作，以及要改用的表達式參數。若您考慮更新應用程式來改用表達式參數，此資料表會有所幫助。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html) 以下章節將提供舊式條件式參數的詳細資訊。 **Topics** + [AttributesToGet (舊版)](LegacyConditionalParameters.AttributesToGet.md) + [AttributeUpdates (舊版)](LegacyConditionalParameters.AttributeUpdates.md) + [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md) + [Expected (舊版)](LegacyConditionalParameters.Expected.md) + [KeyConditions (舊版)](LegacyConditionalParameters.KeyConditions.md) + [QueryFilter (舊版)](LegacyConditionalParameters.QueryFilter.md) + [ScanFilter (舊版)](LegacyConditionalParameters.ScanFilter.md) + [使用舊式參數撰寫條件](LegacyConditionalParameters.Conditions.md) # AttributesToGet (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *ProjectionExpression*](#ProjectionExpression.instead)。 舊版條件式參數 `AttributesToGet` 是一個陣列，包含從 DynamoDB 中擷取的一或多個屬性。如果未提供屬性名稱，則會傳回所有屬性。如果找不到請求的任一屬性，則不會在結果中顯示這些屬性。 `AttributesToGet` 可讓您擷取 List 或 Map 類型的屬性，但無法擷取 List 或 Map 中的個別元素。 請注意，`AttributesToGet` 並不會影響佈建輸送量的耗用。DynamoDB 會根據項目大小判定使用的容量單位數，而不是根據傳回給應用程式的資料量。 ## 改用 *ProjectionExpression* - 範例 假設要從 *Music* 資料表擷取一個項目，但只想傳回部分屬性。您可以搭配 `AttributesToGet` 參數使用`GetItem`請求，如本 AWS CLI 範例所示： ``` aws dynamodb get-item \ --table-name Music \ --attributes-to-get '["Artist", "Genre"]' \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' ``` 您可以改用 `ProjectionExpression`。 ``` aws dynamodb get-item \ --table-name Music \ --projection-expression "Artist, Genre" \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' ``` # AttributeUpdates (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *UpdateExpression*。](#UpdateExpression.instead)。 在 `UpdateItem` 操作中，舊版條件式參數 `AttributeUpdates` 包含要修改的屬性名稱、每個屬性上要執行的動作，以及每個屬性的新值。如果您要更新的屬性是資料表上任何索引的索引鍵屬性，則其類型必須符合資料表描述的 `AttributesDefinition` 中所定義的索引鍵類型。您可以使用 `UpdateItem` 來更新任何非索引鍵屬性。 屬性值不可為 Null。String 和 Binary 類型屬性的長度必須大於零。Set 類型屬性不能為空白。具有空白數值的請求會遭到拒絕，並出現 `ValidationException` 例外狀況。 每個 `AttributeUpdates` 元素包含要修改的屬性名稱，並具有下列資訊： + `Value`：此屬性的新值 (如適用)。 + `Action`：用以指定如何執行更新的數值。此動作僅適用於資料類型為 Number 或 Set 的現有屬性。請勿對其他資料類型使用 `ADD`。 如果在資料表中找到具有指定主索引鍵的項目，則下列各數值會執行以下動作： + `PUT`：將指定屬性新增至項目。如果屬性已存在，則以新數值取代。 + `DELETE`：如果未指定 `DELETE` 的數值，則刪除屬性及其數值。指定數值的資料類型必須符合現有數值的資料類型。 如果指定一組數值，則會從舊的集合中減去該等數值。例如，如果屬性值是集合 `[a,b,c]`，而且 `DELETE` 動作指定 `[a,c]`，則最後屬性值為 `[b]`。指定空集合是一項錯誤。 + `ADD`：如果屬性尚未存在，則將指定數值新增至項目。如果屬性已存在，則 `ADD` 的行為依屬性的資料類型而定： + 如果現有屬性是數字，而 `Value` 亦為數字，則 `Value` 會以數學方式新增至現有屬性。如果 `Value` 是負數，則會從現有屬性減去。 **注意** 如果對更新前不存在的項目使用 `ADD` 增減數值，則 DynamoDB 會以 0 為初始數值。 同樣地，如果對現有項目使用 `ADD` 增減更新前不存在的屬性值，則 DynamoDB 會以 `0` 為初始數值。例如，假設欲更新的項目不具有 *itemcount* 名稱的屬性，但您仍要將此屬性 `ADD` 數字 `3`。DynamoDB 會建立屬性 *itemcount*，將其初始數值設為 `0`，最後再加上 `3`。結果會得到數值為 `3` 的新 *itemcount* 屬性。 + 如果現有的資料類型是集合，而 `Value` 亦為集合，則 `Value` 會附加至現有集合。例如，如果屬性值是集合 `[1,2]`，而且 `ADD` 動作指定 `[3]`，則最後屬性值為 `[1,2,3]`。如果已為集合屬性指定 `ADD` 動作，且指定的屬性類型與現有集合類型不符，則會發生錯誤。 兩個集合必須具有相同的基本資料類型。例如，如果現有的資料類型是一組字串，`Value` 也必須是一組字串。 如果未在資料表中找到具有指定索引鍵的項目，則下列各數值會執行以下動作： + `PUT`：讓 DynamoDB 使用指定的主索引鍵建立新項目，然後新增屬性。 + `DELETE`：不進行任何動作，因為無法從不存在的項目中刪除屬性。成功完成操作，但 DynamoDB 不會建立新項目。 + `ADD`：讓 DynamoDB 使用為屬性值提供的主索引鍵和數字 (或一組數字) 建立項目。僅允許 Number 和 Number Set 資料類型。 如果提供屬於索引鍵一部分的任何屬性，則這些屬性的資料類型必須符合資料表屬性定義中結構描述的資料類型。 ## 改用 *UpdateExpression* - 範例 假設您想修改 *Music* 資料表中的一個項目。您可以搭配 `AttributeUpdates` 參數使用 `UpdateItem`請求，如本 AWS CLI 範例所示： ``` aws dynamodb update-item \ --table-name Music \ --key '{ "SongTitle": {"S":"Call Me Today"}, "Artist": {"S":"No One You Know"} }' \ --attribute-updates '{ "Genre": { "Action": "PUT", "Value": {"S":"Rock"} } }' ``` 您可以改用 `UpdateExpression`。 ``` aws dynamodb update-item \ --table-name Music \ --key '{ "SongTitle": {"S":"Call Me Today"}, "Artist": {"S":"No One You Know"} }' \ --update-expression 'SET Genre = :g' \ --expression-attribute-values '{ ":g": {"S":"Rock"} }' ``` # ConditionalOperator (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 舊版條件式參數 `ConditionalOperator` 是邏輯運算子，可套用至 `Expected`、`QueryFilter` 或 `ScanFilter` 映射中的條件： + AND：如果所有條件評估為 true，則整個映射評估為 true。 + OR：如果至少其中一個條件評估為 true，則整個映射評估為 true。 如果省略 `ConditionalOperator`，則會以 `AND` 為預設。 只有在整個映射評估為 true 時，操作才會成功。 **注意** 此參數不支援 List 或 Map 類型的屬性。 # Expected (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *ConditionExpression*。](#Expected.instead)。 舊版條件式參數 `Expected` 是 `UpdateItem` 操作的條件式區塊。`Expected` 是屬性/條件對的映射。映射的每個元素都包含一個屬性名稱、一個比較運算子，以及一或多個數值。DynamoDB 會使用比較運算子來比較屬性與您提供的數值。對於每個 `Expected` 元素，評估結果皆為 true 或 false。 如果在 `Expected` 映射中指定一個以上元素，所有條件必須根據預設評估為 true。換句話說，條件是使用 `AND` 運算子的組合。(您可以改用 `ConditionalOperator` 參數將條件以 OR 連在一起。若要如此，則至少其中一個條件必須評估為 true，而不是全部都必須評估為 true。) 如果 `Expected` 映射評估為 true，則條件式操作會成功，反之則會失敗。 `Expected` 包含下列各項： + `AttributeValueList`：針對所提供的屬性進行評估的一或多個數值。清單中值的數目依使用的 `ComparisonOperator` 而定。 Number 類型的數值比較為數字。 大於、等於或小於的 String 數值比較是根據 UTF-8 二進位編碼的 Unicode。例如，`a` 大於 `A`，`a` 大於 `B`。 針對 Binary 類型，每當 DynamoDB 比較二進位值時，都會將二進位資料的每個位元組視為不帶正負號。 + `ComparisonOperator`：用於評估 `AttributeValueList` 中屬性的比較程式。執行比較時，DynamoDB 會使用高度一致性讀取。 可以使用下列比較運算子： `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` 以下是每個比較運算子的描述。 + `EQ`：等於。所有資料類型都支援 `EQ`，包括清單和映射。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 + `NE`：不等於。所有資料類型都支援 `NE`，包括清單和映射。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 與所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 + `LE`：小於或等於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `LT`：小於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `GE`：大於或等於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `GT`：大於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `NOT_NULL`：屬性存在。所有資料類型都支援 `NOT_NULL`，包括清單和映射。 **注意** 此運算子會測試屬性是否存在，而不是其資料類型。如果屬性 `a` 的資料類型為 Null，並且是以 `NOT_NULL` 評估，則結果為布林值 `true`。此結果是因為屬性 `a` 存在；其資料類型與 `NOT_NULL` 比較運算子無關。 + `NULL`：屬性不存在。所有資料類型都支援 `NULL`，包括清單和映射。 **注意** 此運算子會測試屬性是否不存在，而不是其資料類型。如果屬性 `a` 的資料類型為 Null，並且是以 `NULL` 評估，則結果為布林值 `false`。這是因為屬性 `a` 存在；其資料類型與 `NULL` 比較運算子無關。 + `CONTAINS`：檢查子序列，或是集合中的數值。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果比較的目標屬性是 String 類型，則運算子會檢查相符子字串。如果比較的目標屬性是 Binary 類型，則運算子會尋找與輸入相符的目標子序列。比較的目標屬性為集合 (`SS`、`NS` 或 `BS`) 時，如果找到與該集合任一成員完全相符的項目，則運算子評估為 true。 清單支援 CONTAINS：當評估 `a CONTAINS b` 時，`a` 可以是清單，但 `b` 不可以是集合、映射或清單。 + `NOT_CONTAINS`：檢查子序列是否不存在，或者集合中的數值是否不存在。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果比較的目標屬性是 String，則運算子會檢查相符子字串是否不存在。如果比較的目標屬性是 Binary，則運算子會檢查與輸入相符的目標子序列是否不存在。比較的目標屬性為集合 (`SS`、`NS` 或 `BS`) 時，如果 `does not` 找到與該集合任一成員完全相符的項目，則運算子評估為 true。 清單支援 NOT\$1CONTAINS：當評估 `a NOT CONTAINS b` 時，`a` 可以是清單，但 `b` 不可以是集合、映射或清單。 + `BEGINS_WITH`：檢查字首。 `AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合類型) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary 類型 (非 Number 或集合類型)。 + `IN`：檢查兩個集合內相符的元素。 `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合類型) 的一或多個 `AttributeValue` 元素。這些屬性會與項目的現有集合類型屬性進行比較。如果輸入集合的任何元素存在於項目屬性中，則表達式評估為 true。 + `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。 `AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合類型) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 下列參數可用來取代 `AttributeValueList` 和 `ComparisonOperator`： + `Value`：DynamoDB 用來與屬性進行比較的數值。 + `Exists`：此為布林值，可讓 DynamoDB 在嘗試條件式操作之前評估數值： + 如果 `Exists` 為 `true`，則 DynamoDB 會查看該屬性值是否已存在於資料表中。如果找到該數值，則條件評估為 true，否則條件評估為 false。 + 如果 `Exists` 為 `false`，則 DynamoDB 會假設屬性值 `not` 存在於資料表中。如果該數值實際上不存在，則假設有效，條件會評估為 true。如果找到該值，則即使假設該值不存在，條件仍會評估為 false。 請注意，`Exists` 預設值為 `true`。 `Value` 和 `Exists` 參數與 `AttributeValueList` 和 `ComparisonOperator` 不相容。請注意，如果同時使用此兩組參數，DynamoDB 會傳回 `ValidationException` 例外狀況。 **注意** 此參數不支援 List 或 Map 類型的屬性。 ## 改用 *ConditionExpression* - 範例 假設您想只在某一條件為 true 的情況下修改 *Music* 資料表中的一個項目。您可以搭配 `Expected` 參數使用 `UpdateItem`請求，如本 AWS CLI 範例所示： ``` aws dynamodb update-item \ --table-name Music \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' \ --attribute-updates '{ "Price": { "Action": "PUT", "Value": {"N":"1.98"} } }' \ --expected '{ "Price": { "ComparisonOperator": "LE", "AttributeValueList": [ {"N":"2.00"} ] } }' ``` 您可以改用 `ConditionExpression`。 ``` aws dynamodb update-item \ --table-name Music \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' \ --update-expression 'SET Price = :p1' \ --condition-expression 'Price <= :p2' \ --expression-attribute-values '{ ":p1": {"N":"1.98"}, ":p2": {"N":"2.00"} }' ``` # KeyConditions (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *KeyConditionExpression*。](#KeyConditionExpression.instead)。 舊版條件式參數 `KeyConditions` 包含 `Query` 操作的選取條件。對於資料表上的查詢，您可以僅對資料表主索引鍵屬性設定條件。您必須將分割區索引鍵名稱和值提供為 `EQ` 條件。您可選擇性地提供指向排序索引鍵的第二個條件。 **注意** 如未提供排序索引鍵條件，則會擷取所有符合分割區索引鍵的項目。如果 `FilterExpression` 或 `QueryFilter` 存在，則會在擷取項目後套用。 對於索引上的查詢，您可以僅對索引鍵屬性設定條件。您必須將索引分割區索引鍵名稱和值提供為 `EQ` 條件。您可選擇提供指向索引排序索引鍵的第二個條件。 每個 `KeyConditions` 元素包含要比較的屬性名稱，並具有下列資訊： + `AttributeValueList`：針對所提供的屬性進行評估的一或多個數值。清單中值的數目依使用的 `ComparisonOperator` 而定。 Number 類型的數值比較為數字。 大於、等於或小於的 String 數值比較是根據 UTF-8 二進位編碼的 Unicode。例如，`a` 大於 `A`，`a` 大於 `B`。 針對 Binary，每當 DynamoDB 比較二進位值時，都會將二進位資料的每個位元組視為不帶正負號。 + `ComparisonOperator`：用於評估屬性的比較程式。例如：等於、大於和小於。 針對 `KeyConditions`，只支援下列比較運算子： `EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN` 以下是這些比較運算子的描述。 + `EQ`：等於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 + `LE`：小於或等於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `LT`：小於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `GE`：大於或等於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `GT`：大於。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 + `BEGINS_WITH`：檢查字首。 `AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合類型) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary 類型 (非 Number 或集合類型)。 + `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。 `AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合類型) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 ## 改用 *KeyConditionExpression* - 範例 假設您想從 *Music* 資料表擷取數個具有相同分割區索引鍵的項目。您可以搭配 `KeyConditions` 參數使用`Query`請求，如本 AWS CLI 範例所示： ``` aws dynamodb query \ --table-name Music \ --key-conditions '{ "Artist":{ "ComparisonOperator":"EQ", "AttributeValueList": [ {"S": "No One You Know"} ] }, "SongTitle":{ "ComparisonOperator":"BETWEEN", "AttributeValueList": [ {"S": "A"}, {"S": "M"} ] } }' ``` 您可以改用 `KeyConditionExpression`。 ``` aws dynamodb query \ --table-name Music \ --key-condition-expression 'Artist = :a AND SongTitle BETWEEN :t1 AND :t2' \ --expression-attribute-values '{ ":a": {"S": "No One You Know"}, ":t1": {"S": "A"}, ":t2": {"S": "M"} }' ``` # QueryFilter (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *FilterExpression*。](#FilterExpression.instead)。 在 `Query` 操作中，舊版條件式參數 `QueryFilter` 是可在項目讀取後評估查詢結果並僅傳回所需值的一個條件。 此參數不支援 List 或 Map 類型的屬性。 **注意** `QueryFilter` 會在項目讀取後套用；篩選程序不會使用任何額外的讀取容量單位。 如果在 `QueryFilter` 映射中提供一個以上條件，所有條件必須根據預設評估為 true。換句話說，條件是使用 `AND` 運算子的組合。(您可以改用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md) 參數將條件以 OR 連在一起。若要如此，則至少其中一個條件必須評估為 true，而不是全部都必須評估為 true。) 請注意，`QueryFilter` 不允許使用索引鍵屬性。您無法在分割區索引鍵或排序索引鍵上定義篩選條件。 每個 `QueryFilter` 元素包含要比較的屬性名稱，並具有下列資訊： + `AttributeValueList`：針對所提供的屬性進行評估的一或多個數值。清單中的數值數目依 `ComparisonOperator` 中指定的運算子而定。 Number 類型的數值比較為數字。 大於、等於或小於的 String 數值比較是以 UTF-8 二進位編碼為基礎。例如，`a` 大於 `A`，`a` 大於 `B`。 針對 Binary 類型，每當 DynamoDB 比較二進位值時，都會將二進位資料的每個位元組視為不帶正負號。 如需在 JSON 中指定資料類型的詳細資訊，請參閱 [DynamoDB 低階 API](Programming.LowLevelAPI.md)。 + `ComparisonOperator`：用於評估屬性的比較程式。例如：等於、大於和小於。 可以使用下列比較運算子： `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` ## 改用 *FilterExpression* - 範例 假設您想查詢 *Music* 資料表，並將條件套用至相符項目。您可以搭配 `QueryFilter` 參數使用 `Query` 請求，如本 AWS CLI 範例所示： ``` aws dynamodb query \ --table-name Music \ --key-conditions '{ "Artist": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S": "No One You Know"} ] } }' \ --query-filter '{ "Price": { "ComparisonOperator": "GT", "AttributeValueList": [ {"N": "1.00"} ] } }' ``` 您可以改用 `FilterExpression`。 ``` aws dynamodb query \ --table-name Music \ --key-condition-expression 'Artist = :a' \ --filter-expression 'Price > :p' \ --expression-attribute-values '{ ":p": {"N":"1.00"}, ":a": {"S":"No One You Know"} }' ``` # ScanFilter (舊版) **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *FilterExpression*。](#FilterExpression2.instead)。 在 `Scan` 操作中，舊版條件式參數 `ScanFilter` 是可評估掃描結果並僅傳回所需值的一個條件。 **注意** 此參數不支援 List 或 Map 類型的屬性。 如果在 `ScanFilter` 映射中指定一個以上條件，所有條件必須根據預設評估為 true。換言之，條件是以 AND 連在一起的。(您可以改用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md) 參數將條件以 OR 連在一起。若要如此，則至少其中一個條件必須評估為 true，而不是全部都必須評估為 true。) 每個 `ScanFilter` 元素包含要比較的屬性名稱，並具有下列資訊： + `AttributeValueList`：針對所提供的屬性進行評估的一或多個數值。清單中的數值數目依 `ComparisonOperator` 中指定的運算子而定。 Number 類型的數值比較為數字。 大於、等於或小於的 String 數值比較是以 UTF-8 二進位編碼為基礎。例如，`a` 大於 `A`，`a` 大於 `B`。 針對 Binary，每當 DynamoDB 比較二進位值時，都會將二進位資料的每個位元組視為不帶正負號。 如需在 JSON 中指定資料類型的詳細資訊，請參閱 [DynamoDB 低階 API](Programming.LowLevelAPI.md)。 + `ComparisonOperator`：用於評估屬性的比較程式。例如：等於、大於和小於。 可以使用下列比較運算子： `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` ## 改用 *FilterExpression* - 範例 假設您想掃描 *Music* 資料表，並將條件套用至相符項目。您可以搭配 `ScanFilter` 參數使用 `Scan` 請求，如本 AWS CLI 範例所示： ``` aws dynamodb scan \ --table-name Music \ --scan-filter '{ "Genre":{ "AttributeValueList":[ {"S":"Rock"} ], "ComparisonOperator": "EQ" } }' ``` 您可以改用 `FilterExpression`。 ``` aws dynamodb scan \ --table-name Music \ --filter-expression 'Genre = :g' \ --expression-attribute-values '{ ":g": {"S":"Rock"} }' ``` # 使用舊式參數撰寫條件 **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 下節說明如何撰寫搭配舊式參數 (例如 `Expected`、`QueryFilter`、`ScanFilter`) 使用的條件。 **注意** 新的應用程式應改用表達式參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 ## 簡單條件 使用屬性值，您可以撰寫條件來與資料表屬性進行比較。條件一律評估為 true 或 false，並且包含下列各項： + `ComparisonOperator`：大於、小於、等於等。 + `AttributeValueList` (選用)：要比較的屬性值。依使用中的 `ComparisonOperator` 而定，`AttributeValueList` 可能包含一兩個或更多數值，或者根本不存在。 下列各節說明各種比較運算子，並附有這些運算子在條件中的用法範例。 ### 不具屬性值的比較運算子 + `NOT_NULL`：如果屬性存在，則本項為 true。 + `NULL`：如果屬性不存在，則本項為 true。 使用這些運算子來檢查屬性存在與否。因為並無可比較的數值，所以不要指定 `AttributeValueList`。 **範例** 如果 *Dimensions* 屬性存在，則下列表達式評估為 true。 ``` ... "Dimensions": { ComparisonOperator: "NOT_NULL" } ... ``` ### 具有一個屬性值的比較運算子 + `EQ`：如果某屬性等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。例如，字串 `"3"` 不等於數字 `3`。此外，數字 `3` 不等於數字集合 `[3, 2, 1]`。 + `NE`：如果某屬性不等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `LE`：如果某屬性小於或等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。 + `LT`：如果某屬性小於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `GE`：如果某屬性大於或等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `GT`：如果某屬性大於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `CONTAINS`：如果某數值在集合內，或者某數值包含另一個數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果比較的目標屬性是 String，則運算子會檢查相符子字串。如果比較的目標屬性是 Binary，則運算子會尋找與輸入相符的目標子序列。比較的目標屬性為集合時，如果找到與該集合任一成員完全相符的項目，則運算子評估為 true。 + `NOT_CONTAINS`：如果某數值*不在*集合內，或者某數值不包含另一個數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果比較的目標屬性是 String，則運算子會檢查相符子字串是否不存在。如果比較的目標屬性是 Binary，則運算子會檢查與輸入相符的目標子序列是否不存在。比較的目標屬性為集合時，如果*未*找到與該集合任一成員完全相符的項目，則運算子評估為 true。 + `BEGINS_WITH`：如果屬性前幾個字元與提供的數值相符，則本項為 true。請勿使用此運算子來比較數字。 `AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個數值。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。 使用這些運算子來比較屬性與數值。您必須指定包含單一數值的 `AttributeValueList`。大多數的運算子要求此數值必須為一個純量，不過 `EQ` 和 `NE` 運算子也支援集合。 **範例** 下列各表達式會評估為 true： + 產品價格大於 100。 ``` ... "Price": { ComparisonOperator: "GT", AttributeValueList: [ {"N":"100"} ] } ... ``` + 產品類別以 Bo 開頭。 ``` ... "ProductCategory": { ComparisonOperator: "BEGINS_WITH", AttributeValueList: [ {"S":"Bo"} ] } ... ``` + 產品有紅色、綠色或黑色款式： ``` ... "Color": { ComparisonOperator: "EQ", AttributeValueList: [ [ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ] ] } ... ``` **注意** 比較集合資料類型時，元素的順序無關緊要。無論在請求中指定何順序，DynamoDB 只會傳回具有相同一組數值的項目。 ### 具有兩個屬性值的比較運算子 + `BETWEEN`：如果某數值介於下限和上限之間 (含端點在內)，則本項為 true。 `AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 使用此運算子判定屬性值是否在某範圍內。`AttributeValueList` 必須包含同為 String、Number 或 Binary 類型的兩個純量元素。 **範例** 如果產品價格介於 100 和 200 之間，則下列表達式評估為 true。 ``` ... "Price": { ComparisonOperator: "BETWEEN", AttributeValueList: [ {"N":"100"}, {"N":"200"} ] } ... ``` ### 具有 *N* 屬性值的比較運算子 + `IN`：如果某數值等於列舉清單中任何數值，則本項為 true。清單中僅支援純量值，不支援集合。目標屬性必須為相同的類型和確切數值才相符。 `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合) 的一或多個元素。這些屬性會與項目的現有非集合類型屬性進行比較。如果輸入集合的*任何*元素存在於項目屬性中，則表達式評估為 true。 `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合) 的一或多個數值。比較的目標屬性必須為相同的類型和確切數值才相符。String 一律不與 String 集合相符。 使用此運算子判定提供的數值是否在列舉清單內。您可以在 `AttributeValueList` 中指定任意數量的純量值，但所有純量值必須屬於同一資料類型。 **範例** 如果 *Id* 的數值為 201、203 或 205，則下列表達式評估為 true。 ``` ... "Id": { ComparisonOperator: "IN", AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ] } ... ``` ## 使用多個條件 DynamoDB 可讓您將多個條件結合成複雜的表達式。您可以提供至少兩個表達式來執行此操作，另可選用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md)。 根據預設，指定一個以上條件時，*所有*條件必須評估為 true，以便整個表達式評估為 true。換言之，會執行隱含的 *AND* 操作。 **範例** 如果產品為一本至少有 600 頁的書，則下列表達式評估為 true。這兩個條件皆須評估為 true，因為兩者隱含地以 *AND* 連在一起。 ``` ... "ProductCategory": { ComparisonOperator: "EQ", AttributeValueList: [ {"S":"Book"} ] }, "PageCount": { ComparisonOperator: "GE", AttributeValueList: [ {"N":600"} ] } ... ``` 可以使用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md) 來清楚表示會執行一個 *AND* 操作。下列範例與前一範例的表現方式相同。 ``` ... "ConditionalOperator" : "AND", "ProductCategory": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"N":"Book"} ] }, "PageCount": { "ComparisonOperator": "GE", "AttributeValueList": [ {"N":600"} ] } ... ``` 您也可以將 `ConditionalOperator` 設定為 *OR*，這表示其中*至少一個*條件必須評估為 true。 **範例** 如果產品為一台登山單車、屬於特定品牌，或者其價格大於 100，則下列表達式評估為 true。 ``` ... ConditionalOperator : "OR", "BicycleType": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Mountain" ] }, "Brand": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Brand-Company A" ] }, "Price": { "ComparisonOperator": "GT", "AttributeValueList": [ {"N":"100"} ] } ... ``` **注意** 在複雜的表達式中，會按第一到最後一個條件的順序依序處理條件。 無法在單一表達式中同時使用 AND 和 OR。 ## 其他條件式運算子 在舊版 DynamoDB 當中，`Expected` 參數在條件式寫入方面有不同的表現方式。`Expected` 映射中的每個項目顯示 DynamoDB 要檢查的屬性名稱，並具有下列資訊： + `Value`：要與屬性比較的值。 + `Exists`：判定在嘗試操作之前是否已有此數值。 DynamoDB 持續支援 `Value` 和 `Exists` 選項；不過，這些選項僅能測試相等條件，或者是否存在某屬性。建議您改用 `ComparisonOperator` 和 `AttributeValueList`，因為這些選項可讓您建構更廣泛的條件。 **Example** `DeleteItem` 可以查看書籍是否已絕版，並且只在此條件為 true 時才刪除書籍。以下為使用舊式條件的 AWS CLI 範例： ``` aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "Exists": true, "Value": {"BOOL":false} } }' ``` 以下範例顯示相同項目，但不使用舊式條件： ``` aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"BOOL":false} ] } }' ``` **Example** `PutItem` 操作可防止覆寫已有相同主索引鍵屬性的現有項目。以下為使用舊式條件的範例： ``` aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "Exists": false } }' ``` 以下範例顯示相同項目，但不使用舊式條件： ``` aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "ComparisonOperator": "NULL" } }' ``` **注意** 針對 `Expected` 映射中的條件，請勿搭配 `ComparisonOperator` 和 `AttributeValueList` 使用舊式的 `Value` 和 `Exists` 選項。若採取此法，條件式寫入將會失敗。