Syarat penulisan dengan parameter warisan

catatan

Kami menyarankan agar Anda menggunakan parameter ekspresi yang baru, bukan parameter warisan ini, jika memungkinkan. Untuk informasi selengkapnya, lihat Menggunakan ekspresi di DynamoDB.

Bagian berikut menjelaskan cara menulis syarat untuk digunakan dengan parameter warisan, seperti Expected, QueryFilter, dan ScanFilter.

catatan

Aplikasi baru harus menggunakan parameter ekspresi sebagai gantinya. Untuk informasi selengkapnya, lihat Menggunakan ekspresi di DynamoDB.

Syarat sederhana

Dengan nilai atribut, Anda dapat menulis syarat untuk perbandingan terhadap atribut tabel. Syarat selalu bernilai true atau false, dan terdiri dari:

• ComparisonOperator – lebih besar dari, kurang dari, sama dengan, dan sebagainya.

• AttributeValueList (opsional) – nilai atribut untuk dibandingkan. Tergantung pada ComparisonOperator yang sedang digunakan, AttributeValueList mungkin berisi satu, dua, atau lebih nilai; atau mungkin tidak ada sama sekali.

Bagian berikut menjelaskan berbagai operator perbandingan, beserta contoh cara menggunakannya dalam syarat.

Operator perbandingan tanpa nilai atribut

• NOT_NULL - true jika atribut ada.

• NULL - true jika atribut tidak ada.

Gunakan operator ini untuk memeriksa apakah atribut ada, atau tidak ada. Karena tidak ada nilai untuk dibandingkan, jangan tentukan AttributeValueList.

Contoh

Ekspresi berikut bernilai true jika ada atribut Dimensi.

...
    "Dimensions": {
         ComparisonOperator: "NOT_NULL"
    }
...

Operator perbandingan dengan satu nilai atribut

• EQ - true jika atribut sama dengan sebuah nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, Biner, Set String, Set Angka, atau Set Biner. Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok. Misalnya, string "3" tidak sama dengan angka 3. Selain itu, angka 3 tidak sama dengan set angka [3, 2, 1].

• NE - true jika atribut tidak sama dengan sebuah nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, Biner, Set String, Set Angka, atau Set Biner. Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok.

• LE - true jika atribut kurang dari atau sama dengan sebuah nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok.

• LT - true jika atribut kurang dari sebuah nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok.

• GE - true jika atribut lebih besar dari atau sama dengan suatu nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok.

• GT - true jika atribut lebih besar dari sebuah nilai.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok.

• CONTAINS - true jika nilai ada dalam suatu set, atau jika satu nilai berisi nilai lain.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika atribut target perbandingan berupa String, operator memeriksa kecocokan substring. Jika atribut target perbandingan berupa Biner, operator mencari urutan berikutnya dari target yang cocok dengan input. Jika atribut target perbandingan adalah suatu set, operator bernilai true jika menemukan kecocokan sama persis dengan anggota set tersebut.

• NOT_CONTAINS - true jika nilai tidak ada dalam suatu set, atau jika satu nilai tidak berisi nilai lainnya.

  AttributeValueList hanya dapat berisi satu nilai berjenis String, Angka, atau Biner (bukan set). Jika atribut target perbandingan adalah String, operator memeriksa tidak adanya kecocokan substring. Jika atribut target perbandingan adalah Biner, operator mencari tidak adanya urutan berikutnya dari target yang cocok dengan input. Jika atribut target perbandingan adalah sebuah set, operator akan bernilai true jika tidak menemukan kecocokan yang sama persis dengan anggota set.

• BEGINS_WITH - true jika beberapa karakter pertama atribut cocok dengan nilai yang disediakan. Jangan gunakan operator ini untuk membandingkan angka.

  AttributeValueList hanya dapat berisi satu nilai berjenis String atau Biner (bukan Angka atau set). Atribut target perbandingan harus berupa String atau Biner (bukan Angka atau set).

Gunakan operator ini untuk membandingkan atribut dengan sebuah nilai. Anda harus menentukan AttributeValueList yang berisi nilai tunggal. Untuk sebagian besar operator, nilai ini harus berupa skalar; tetapi, operator EQ dan NE juga mendukung set.

Contoh

Ekspresi berikut bernilai true jika:

• Harga produk lebih besar dari 100.

  ...
      "Price": {
          ComparisonOperator: "GT",
          AttributeValueList: [ {"N":"100"} ]
      }
  ...

• Kategori produk dimulai dengan "Bo".

  ...
      "ProductCategory": {
          ComparisonOperator: "BEGINS_WITH",
          AttributeValueList: [ {"S":"Bo"} ]
      }
  ...

• Produk tersedia dalam warna merah, hijau, atau hitam:

  ...
      "Color": {
          ComparisonOperator: "EQ",
          AttributeValueList: [
              [ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
          ]
      }
  ...

  catatan

  Saat membandingkan jenis data set, urutan elemen tidak menjadi masalah. DynamoDB hanya akan mengembalikan item dengan set nilai yang sama, terlepas dari urutan yang Anda tentukan dalam permintaan Anda.

Operator perbandingan dengan dua nilai atribut

• BETWEEN - true jika nilai adalah antara batas bawah dan batas atas, termasuk titik akhir.

  AttributeValueList harus berisi dua elemen dari jenis yang sama, baik String, Angka, atau Biner (bukan set). Suatu atribut target cocok jika nilai target lebih besar dari, atau sama dengan, elemen pertama dan kurang dari, atau sama dengan, elemen kedua. Jika item berisi nilai dengan jenis berbeda dari jenis yang ditentukan dalam permintaan, nilainya tidak cocok.

Gunakan operator ini untuk menentukan apakah nilai atribut termasuk dalam kisaran. AttributeValueList harus berisi dua elemen skalar berjenis yang sama - String, Angka, atau Biner.

Contoh

Ekspresi berikut bernilai true jika harga produk adalah antara 100 dan 200.

...
    "Price": {
        ComparisonOperator: "BETWEEN",
        AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
    }
...

Operator perbandingan dengan nilai atribut n

• IN - true jika nilai sama dengan salah satu nilai dalam daftar yang dienumerasi. Hanya nilai skalar yang didukung dalam daftar, bukan set. Atribut target harus memiliki jenis yang sama dan nilai persis agar cocok.

  AttributeValueList dapat berisi satu atau beberapa elemen jenis String, Angka, atau Biner (bukan set). Atribut ini dibandingkan dengan atribut jenis non-set yang ada dari suatu item. Jika elemen apa pun dari set input ada dalam atribut item, ekspresi bernilai true.

  AttributeValueList dapat berisi satu atau beberapa nilai berjenis String, Angka, atau Biner (bukan set). Atribut target perbandingan harus memiliki jenis yang sama dan nilai persis agar cocok. Sebuah String tidak pernah cocok dengan set String.

Gunakan operator ini untuk menentukan apakah nilai yang disediakan berada dalam daftar yang dienumerasi. Anda dapat menentukan nilai skalar apa pun di AttributeValueList, tetapi semua angka tersebut harus dari jenis data yang sama.

Contoh

Ekspresi berikut bernilai true jika nilai untuk Id adalah 201, 203, atau 205.

...
    "Id": {
        ComparisonOperator: "IN",
        AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
    }
...

Menggunakan beberapa syarat

DynamoDB memungkinkan Anda menggabungkan beberapa syarat untuk membentuk ekspresi kompleks. Anda melakukan ini dengan menyediakan setidaknya dua ekspresi, dengan ConditionalOperator (warisan) opsional.

Secara default, ketika Anda menentukan lebih dari satu syarat, semua syarat harus bernilai true agar seluruh ekspresi bernilai true. Dengan kata lain, ANDoperasi implisit terjadi.

Contoh

Ekspresi berikut bernilai true jika produk adalah buku yang memiliki setidaknya 600 halaman. Kedua kondisi harus dievaluasi menjadi benar, karena keduanya secara implisit ANDdisatukan.

... 
    "ProductCategory": { 
        ComparisonOperator: "EQ",
        AttributeValueList: [ {"S":"Book"} ]
    },
    "PageCount": { 
        ComparisonOperator: "GE",
        AttributeValueList: [ {"N":600"} ]
    }
...

Anda dapat menggunakan ConditionalOperator (warisan) untuk mengklarifikasi bahwa ANDoperasi akan berlangsung. Contoh berikut berperilaku dengan cara yang sama seperti sebelumnya.

...   
    "ConditionalOperator" : "AND",
    "ProductCategory": { 
        "ComparisonOperator": "EQ",
        "AttributeValueList": [ {"N":"Book"} ]
    },
    "PageCount": { 
        "ComparisonOperator": "GE",
        "AttributeValueList": [ {"N":600"} ]
    }
...

Anda juga dapat mengatur ConditionalOperator menjadi OR, yang berarti bahwa setidaknya salah satu syarat harus bernilai true.

Contoh

Ekspresi berikut bernilai true jika produk adalah sepeda gunung, jika produk tersebut adalah nama merek tertentu, atau jika harganya lebih besar dari 100.

... 
    ConditionalOperator : "OR",
    "BicycleType": { 
        "ComparisonOperator": "EQ",
        "AttributeValueList": [ {"S":"Mountain" ]
    },
    "Brand": { 
        "ComparisonOperator": "EQ",
        "AttributeValueList": [ {"S":"Brand-Company A" ]
    },
    "Price": { 
        "ComparisonOperator": "GT",
        "AttributeValueList": [ {"N":"100"} ]
    }
...

catatan

Dalam ekspresi yang kompleks, syarat diproses secara berurutan, mulai syarat pertama hingga terakhir.

Anda tidak dapat menggunakan keduanya AND dan OR dalam satu ekspresi.

Operator bersyarat lainnya

Dalam rilis DynamoDB sebelumnya, parameter Expected berperilaku berbeda untuk penulisan bersyarat. Setiap item dalam peta Expected mewakili nama atribut untuk diperiksa DynamoDB, beserta hal berikut:

• Value – nilai untuk dibandingkan terhadap atribut.

• Exists – menentukan apakah nilai ada sebelum mencoba operasi.

Opsi Value dan Exists tetap didukung dalam DynamoDB; tetapi, keduanya hanya membiarkan Anda menguji syarat kesetaraan, atau apakah atribut ada. Kami menyarankan agar Anda menggunakan ComparisonOperator dan AttributeValueList sebagai gantinya, karena opsi ini memungkinkan Anda membangun berbagai syarat yang lebih luas.

contoh

DeleteItem dapat memeriksa untuk melihat apakah buku tidak lagi dalam publikasi, dan hanya menghapusnya jika syarat ini bernilai true. Berikut adalah contoh AWS CLI menggunakan syarat warisan:

aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{
        "Id": {"N":"600"}
    }' \
    --expected '{
        "InPublication": { 
            "Exists": true, 
            "Value": {"BOOL":false} 
        } 
    }'

Contoh berikut melakukan hal yang sama, tetapi tidak menggunakan syarat warisan:

aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{
        "Id": {"N":"600"}
    }' \
    --expected '{
        "InPublication": { 
            "ComparisonOperator": "EQ", 
            "AttributeValueList": [ {"BOOL":false} ]
        } 
    }'

contoh

Operasi PutItem dapat melindungi terhadap penimpaan item yang ada dengan atribut kunci primer yang sama. Berikut adalah contoh penggunaan syarat warisan:

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item '{
      "Id": {"N":"500"},
        "Title": {"S":"Book 500 Title"}
    }' \
    --expected '{
        "Id": { "Exists": false } 
    }'

Contoh berikut melakukan hal yang sama, tetapi tidak menggunakan syarat warisan:

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item '{
      "Id": {"N":"500"},
        "Title": {"S":"Book 500 Title"}
    }' \
    --expected '{
        "Id": { "ComparisonOperator": "NULL" } 
    }'

catatan

Untuk syarat di peta Expected, jangan gunakan opsi warisan Value dan Exists bersama dengan ComparisonOperator dan AttributeValueList. Jika Anda melakukan hal ini, penulisan bersyarat Anda akan gagal.