DynamoDB GetItem di Python (boto3)

get_item mengambil satu item berdasarkan primary key lengkap-nya. Client tingkat rendah boto3 (boto3.client("dynamodb")) berbicara DynamoDB JSON di kedua arah, jadi key-nya masuk terbungkus bersama tipenya dan item-nya kembali dengan cara yang sama. Bedanya dengan query dan scan dibahas di aksi berbasis item.

Kode

import boto3

client = boto3.client("dynamodb")

response = client.get_item(
    TableName="Music",
    Key={"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
    ProjectionExpression="#proj0, #proj1, #proj2, #proj3",
    ExpressionAttributeNames={"#proj0": "Artist", "#proj1": "SongTitle", "#proj2": "AlbumTitle", "#proj3": "Year"},
)

item = response.get("Item")
if item is None:
    print("Item not found")
else:
    print(item)

Penjelasan

Yang meleset mengembalikan respons tanpa key Item sama sekali. Bukan None, bukan dict kosong. Membaca tabel yang sama untuk key yang tidak ada, key tingkat teratas responsnya persis:

['ResponseMetadata']

Itulah sebabnya cuplikan di atas memakai response.get("Item"). response["Item"] melempar KeyError pada jalur not-found yang biasa saja, dan begitulah baris yang hilang berubah jadi 500 di sebuah web handler. Anda tetap ditagih untuk pembacaan itu: halaman kapasitas baca AWS menyatakan bahwa "if you perform a read operation on an item that doesn't exist, DynamoDB will still consume read throughput as outlined above" (diambil 2026-07-28).

Year adalah kata reserved, itulah sebabnya cuplikan yang dihasilkan memberi alias pada setiap atribut yang diproyeksikan. Buang alias #proj-nya lalu berikan ProjectionExpression="Year" dan engine menolak pembacaan itu:

ValidationException: Invalid ProjectionExpression: Attribute name is a reserved keyword; reserved keyword: Year

Memberi alias tanpa syarat tidak memakan biaya apa pun dan menghapus seluruh kelas kegagalan itu. Daftar lengkapnya sepanjang 573 kata; lihat "Attribute name is a reserved keyword".

Empat cara salah menyusun Key, tiga pesan yang berbeda. Ketiganya layak dibedakan, karena tak satu pun di antaranya adalah error "provided key element does not match the schema" yang orang harapkan. Direproduksi terhadap tabel Music dengan key Artist (partition) + SongTitle (sort):

Perhatikan bahwa atribut key yang hilang dan yang berlebih menghasilkan pesan yang sama, jadi "number of conditions" berarti "Anda tidak memberi saya persis key schema-nya", bukan "Anda memberi terlalu sedikit".

ProjectionExpression memangkas payload, bukan tagihan. Membaca item berukuran ~15 KB dengan tiga cara memakai ReturnConsumedCapacity="TOTAL":

full item, eventually consistent          CapacityUnits: 2.0
ProjectionExpression="#y" (Year only)     CapacityUnits: 2.0
ProjectionExpression="#y" + ConsistentRead  CapacityUnits: 4.0

Proyeksi itu mengubah responsnya dari ~15 KB menjadi satu angka dan tidak mengubah biayanya sedikit pun. AWS menyatakannya terang-terangan: "The number of capacity units consumed will be the same whether you request all of the attributes (the default behavior) or just some of them (using a projection expression)" (Query API Reference, diambil 2026-07-28). ConsistentRead=True adalah satu-satunya flag di daftar itu yang menggerakkan angkanya, dan ia melipatgandakannya. Lihat projection expression untuk memahami proyeksi sebenarnya untuk apa.

API resource adalah kontrak yang berbeda, bukan sekadar ejaan yang lebih enak. boto3.resource("dynamodb").Table("Music").get_item(...) mengembalikan Python biasa dan setiap angka sebagai decimal.Decimal:

{'Artist': 'Arturo Sandoval', 'AlbumTitle': 'Danzon', 'Awards': Decimal('0'), 'Year': Decimal('1994'), 'SongTitle': 'Cubano Chant'}

Itu pedang bermata dua. Menulis balik lewat API yang sama dengan float melempar error sebelum permintaannya meninggalkan mesin Anda:

TypeError: Float types are not supported. Use Decimal types instead.

Kalau yang satu itu menggigit Anda, "Float types are not supported" punya perbaikannya. Mencampur kedua API dalam satu codebase adalah jebakan sesungguhnya: client tingkat rendah dengan senang hati menerima {"N": "1.5"} yang justru akan ditolak API resource.

Error datang sebagai exception botocore, dan boto3 memberi mereka kelas sungguhan. Pada 1.43.58 objek yang dilempar untuk kondisi yang gagal adalah ConditionalCheckFailedException, sebuah subclass ClientError, jadi except ClientError plus pemeriksaan err.response["Error"]["Code"] maupun except client.exceptions.ConditionalCheckFailedException sama-sama bekerja. Pilih mana pun yang sudah dipakai codebase Anda; jangan mencocokkan pada str(e).

Lakukan secara visual

Sebelum Anda memberi alias secara manual: pemeriksa reserved word DynamoDB gratis menerima nama atribut Anda, memberi tahu 573 kata reserved mana yang Anda tabrak, dan memancarkan map ExpressionAttributeNames siap tempel.

Untuk menjelajahi tabel dan menjalankan GetItem terhadap data Anda sendiri — bentuk key, grid hasil, salin kembali permintaannya sebagai boto3 — unduh DynoTable.

Panduan terkait

• Query vs. Scan — kapan satu get_item mengalahkan query.
• Tipe data DynamoDB — bagaimana setiap tipe atribut direpresentasikan dalam DynamoDB JSON.
• DynamoDB ResourceNotFoundException — error pertama yang biasa muncul di sini: nama tabel atau Region salah.
• "The provided key element does not match the schema" — key yang Anda berikan tidak cocok dengan key schema tabel.

Referensi

• GetItem — Amazon DynamoDB API Reference
• get_item — Boto3 DynamoDB.Client Reference
• Read consistency — Amazon DynamoDB Developer Guide
• Capacity unit consumption — Amazon DynamoDB Developer Guide

Direproduksi 2026-07-28 terhadap DynamoDB Local (amazon/dynamodb-local) di port 9000 dengan boto3 1.43.58 / botocore 1.43.58. Setiap pesan dan angka kapasitas di atas adalah keluaran engine, disalin apa adanya. DynamoDB Local bukanlah layanan aslinya; di tempat keduanya diketahui merumuskan sebuah error secara berbeda, kami menyebutkannya di halaman error terkait.