Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Comprensione dei record CDC
**Importante**
Questa funzionalità viene fornita come AWS anteprima ed è soggetta a modifiche. Per ulteriori informazioni, consulta la sezione 2, Beta e anteprime, nei Termini di [AWS servizio](https://aws.amazon.com/service-terms/). Per ulteriori informazioni sui prezzi degli stream CDC, consulta la pagina dei prezzi di [Aurora DSQL](https://aws.amazon.com/rds/aurora/dsql/pricing/).
Prima della disponibilità generale, aggiungeremo nuovi tipi di operazioni (`"op": "u"`per gli aggiornamenti) al payload dello stream. Per garantire che l'applicazione gestisca queste modifiche senza modifiche, considera qualsiasi `op` valore non riconosciuto come un problema, applicando il payload. `after` Per informazioni dettagliate, vedi [Comprensione dei record CDC](#cdc-record-format).
Aurora DSQL CDC fornisce ogni modifica come record JSON. Il record utilizza una struttura a busta con tipo di operazione, immagini di riga prima e dopo e metadati di origine.
## In che modo i record vengono mappati su Amazon Kinesis
Aurora DSQL scrive ogni record CDC come un singolo record Kinesis. Il `Data` campo del record Kinesis contiene il payload JSON. Aurora DSQL utilizza una chiave di partizione Kinesis randomizzata per distribuire i record CDC in modo uniforme tra gli shard. Per leggere tutte le modifiche, utilizza tutti gli shard del flusso di dati Kinesis. Se un record supera il limite di dimensione dei record Kinesis, Aurora DSQL lo divide tra più record Kinesis. Per informazioni dettagliate, vedi [Gestione di dischi di grandi dimensioni](#cdc-oversized-records).
**Nota**
Un record Kinesis ha un `Data` blob. I valori della chiave primaria vengono visualizzati nel campo del payload JSON per le eliminazioni o `before` nel campo per gli inserimenti e gli aggiornamenti`after`. Per estrarre la chiave primaria per l'elaborazione a valle, leggila dal campo appropriato nel payload.
## Chiave primaria nel payload
Per le tabelle con una chiave primaria, i valori della colonna della chiave primaria vengono visualizzati nel payload:
+ Per gli **inserimenti** e **gli aggiornamenti**, il payload include le colonne della chiave primaria insieme a tutte le altre colonne del campo. `after`
+ Per le **eliminazioni**, le colonne della chiave principale vengono visualizzate nel campo. `before`
Ad esempio, considera una tabella con una chiave primaria composita:
```
CREATE TABLE order_items (
order_id INT,
item_id INT,
quantity INT,
price NUMERIC,
PRIMARY KEY (order_id, item_id)
);
```
Un'eliminazione su questa tabella produce un payload dove`"before": {"order_id": 1001, "item_id": 42}`.
## Registra il payload
Il payload utilizza il seguente formato di busta JSON.
**Esempio INSERT**
L'esempio seguente mostra un record CDC per un'operazione di inserimento:
```
{
"type": "full",
"op": "c",
"before": null,
"after": {"order_id": 1001, "item_id": 42, "quantity": 5, "price": "29.99"},
"source": {
"version": "1.0",
"ts_ms": 1705318200000,
"ts_ns": 1705318200000000000,
"txId": "ffthunp5stx6ffs2vyfqoatmfu",
"schema": "public",
"table": "order_items",
"db": "postgres",
"cluster": "kmabugltfmjdaj2siqr2qbxgju"
},
"ts_ms": 1705318200125,
"ts_ns": 1705318200125483291
}
```
**Esempio UPDATE**
L'esempio seguente mostra come apparirà un record CDC prodotto da un'`UPDATE`istruzione dopo l'inizio dell'emissione di Aurora DSQL: `op: "u"`
**Importante**
Attualmente Aurora DSQL emette sia `op: "c"` per gli inserimenti che per gli aggiornamenti. Verrà emessa una versione successiva `op: "u"` per gli aggiornamenti e per gli inserimenti. `op: "c"` Progetta la tua app in modo che sia `u` gestibile`c`, `d` in modo che il consumatore continui a lavorare durante la transizione.
```
{
"type": "full",
"op": "u",
"before": null,
"after": {"order_id": 1001, "item_id": 42, "quantity": 10, "price": "29.99"},
"source": {
"version": "1.0",
"ts_ms": 1705318300000,
"ts_ns": 1705318300000000000,
"txId": "qvtiesgmd55cvlfukm3dfuotji",
"schema": "public",
"table": "order_items",
"db": "postgres",
"cluster": "kmabugltfmjdaj2siqr2qbxgju"
},
"ts_ms": 1705318300125,
"ts_ns": 1705318300125483291
}
```
**Esempio DELETE**
Per le eliminazioni su tabelle con una chiave primaria, il `before` campo contiene i valori della chiave primaria della riga eliminata:
```
{
"type": "full",
"op": "d",
"before": {"order_id": 1001, "item_id": 42},
"after": null,
"source": {
"version": "1.0",
"ts_ms": 1705318400000,
"ts_ns": 1705318400000000000,
"txId": "xyzabc123def456ghi789jklmno",
"schema": "public",
"table": "order_items",
"db": "postgres",
"cluster": "kmabugltfmjdaj2siqr2qbxgju"
},
"ts_ms": 1705318400125,
"ts_ns": 1705318400125483291
}
```
## Campi del payload
| Campo | Description |
| --- |--- |
| type | Il tipo di record. fullper un record completo che include dati in linea before e after valori. chunkedper un record principale che fa riferimento a record di frammenti per una o entrambe le immagini. fragmentper una singola parte di un'immagine suddivisa in blocchi. Per informazioni dettagliate, vedi [Gestione di dischi di grandi dimensioni](#cdc-oversized-records). |
| op | Tipo di operazione. c= crea (inserisci), u = aggiorna, d = elimina. Attualmente Aurora DSQL emette sia c per gli inserimenti che per gli aggiornamenti. Verrà emessa una versione successiva u per gli aggiornamenti e per gli inserimenti. c Progetta la tua app per gestire tutti e tre i valori. |
| before | Per le eliminazioni su tabelle con una chiave primaria, contiene i valori della chiave primaria della riga eliminata. Aurora DSQL imposta questo campo null per inserimenti, aggiornamenti ed eliminazioni su tabelle senza chiave primaria. |
| after | Lo stato completo della riga dopo la modifica, incluse tutte le colonne. Aurora DSQL imposta questo campo su per null le eliminazioni. |
| chunked | Presente solo quando lo è. type chunked Contiene i metadati di riassemblaggio per l'beforeimmagine, l'afterimmagine o entrambi. Aurora DSQL omette l'immagine suddivisa in blocchi dal primo livello before o after dal campo e la colloca invece sotto. chunked Per informazioni dettagliate, vedi [Gestione di dischi di grandi dimensioni](#cdc-oversized-records). |
| source.version | La versione del formato dei metadati di origine CDC. La versione corrente è 1.0. |
| source.ts\_ms | Il timestamp di conferma della transazione in millisecondi dall'epoca Unix, Coordinated Universal Time (UTC). |
| source.ts\_ns | Timestamp di conferma della transazione in nanosecondi, UTC. Il timestamp con la massima precisione disponibile. Utilizza questo campo per stabilire l'ordine totale delle transazioni. |
| source.txId | Un identificatore di transazione univoco, codificato come base32. Tutti i record della stessa transazione condividono lo stesso valore. txId Utilizzare questo campo per raggruppare i record che appartengono alla stessa transazione. |
| source.schema | Il nome dello schema PostgreSQL (ad esempio,). public |
| source.table | Il nome della tabella. |
| source.db | Nome del database. Sempre postgres per Aurora DSQL. |
| source.cluster | L'identificatore del cluster Aurora DSQL. |
| ts\_ms | L'ora in cui il sistema CDC ha elaborato il record, in millisecondi, UTC. La differenza tra ts\_ms e source.ts\_ms è una misura del ritardo di replica. |
| ts\_ns | L'ora in cui il sistema CDC ha elaborato il record, in nanosecondi, UTC. |
## Dettagli sul formato
I seguenti dettagli descrivono come Aurora DSQL CDC formatta i record. Progetta la tua app per gestire questi comportamenti.
+ **Immagine finale completa per inserti e aggiornamenti.** Aurora DSQL include lo stato completo della riga nel `after` campo per tutte le scritture. Il `before` campo serve `null` per inserimenti e aggiornamenti. Attualmente vengono utilizzati sia gli inserti che gli aggiornamenti`op: "c"`, ma verrà emessa `op: "u"` una versione successiva per gli aggiornamenti. Progetta la tua app in modo che utilizzi `source.ts_ns` ogni chiave primaria per l'ordinazione anziché affidarti al `op` campo per distinguere tra inserti e aggiornamenti.
+ **Post-change solo lo stato delle righe.** I record CDC includono lo stato completo della riga dopo ogni modifica. Lo stato della riga prima di un aggiornamento non è incluso. Per le eliminazioni su tabelle con una chiave primaria, il `before` campo contiene i valori della chiave primaria.
+ **Tipi numerici serializzati come stringhe.** Aurora DSQL serializza `numeric` e `decimal` valuta come stringhe JSON per preservare la precisione esatta.
+ **Dati binari codificati come Base64.** Aurora DSQL codifica i `bytea` valori come stringhe Base64.
+ **Valori numerici e a virgola mobile speciali.** Aurora DSQL serializza NaN e ±Infinity come stringhe e. `"NaN"` `"Infinity"` `"-Infinity"` Questo vale per e tipi. `real` `double precision` `numeric`
+ **Colonne JSON serializzate come stringhe JSON.** Aurora DSQL serializza i valori delle `json` colonne come stringhe JSON che contengono il testo JSON non elaborato memorizzato nella colonna. Analizza il valore della stringa nella tua app (ad esempio, con `JSON.parse` in JavaScript o `json.loads` in Python) per accedere al valore JSON sottostante.
+ **Valori di overflow emessi come null.** Se un valore non può essere rappresentato nel tipo JSON di destinazione durante la serializzazione, Aurora DSQL emette JSON per quella colonna. `null` Ciò si applica ai `interval` valori i cui microsecondi totali superano l'intervallo di numeri interi con segno a 64 bit (±9.223.372.036.854.775.807 microsecondi, circa ±292.271 anni). Progetta `null` la tua app per gestire valori imprevisti in colonne che non possono essere annullate nello schema del database.
+ **I record sovradimensionati si dividono in blocchi.** Se un record supera il limite di dimensione del record di Amazon Kinesis, Aurora DSQL divide l'immagine `after` o l'immagine `before` interessata in frammenti e li consegna come record Kinesis separati in modo da ricevere comunque la modifica. Progetta la tua app per riassemblare le immagini. Per informazioni dettagliate, vedi [Gestione di dischi di grandi dimensioni](#cdc-oversized-records).
## Gestione di dischi di grandi dimensioni
Quando il codice JSON serializzato di un record CDC supera i 9 MiB, Aurora DSQL `before` and/or `after` divide le immagini, fornendo più record Kinesis. Ogni record contiene un `type` campo di primo livello che ne indica la struttura: `full` per un record completo, per un record principale che fa riferimento ai frammenti e `chunked` per una singola parte di un'immagine suddivisa in blocchi. `fragment` I `ts_ns` campi`op`, `source``ts_ms`, e di un record principale suddiviso in blocchi si comportano come in un record completo. I record che rientrano in un singolo record Kinesis sono `type` impostati `full` e non richiedono alcuna gestione aggiuntiva.
A `chunk_id` è stabile tra i tentativi. Se Aurora DSQL riconsegna nuovamente un frammento, ha lo stesso `chunk_id` contenuto della distribuzione originale, in modo che l'app possa continuare a memorizzare nel buffer con lo stesso identificatore senza gestire set parziali dei tentativi precedenti.
**Record principale**
Un record principale suddiviso in blocchi sostituisce il livello `before` o il `after` campo superiore dell'immagine divisa con un `chunked` oggetto che descrive come riassemblarla. Ogni voce sottostante `chunked` ha un `chunk_id` (l'identificatore che collega i frammenti a questo record), `total_fragments` (il numero di frammenti che compongono quell'immagine) e `crc32c` (un checksum CRC32C, come stringa decimale, sul testo dell'immagine riassemblato). Se un'immagine è in linea e l'altra è suddivisa in blocchi, l'immagine in linea viene comunque visualizzata al livello superiore come valore o. `null`
```
{
"type": "chunked",
"op": "c",
"before": null,
"after": null,
"source": {
"version": "1.0",
"ts_ms": 1705318200000,
"ts_ns": 1705318200000000000,
"txId": "ffthunp5stx6ffs2vyfqoatmfu",
"schema": "public",
"table": "order_items",
"db": "postgres",
"cluster": "{{cluster-id}}"
},
"chunked": {
"after": {
"chunk_id": "{{chunk-id}}",
"total_fragments": 3,
"crc32c": "2073618257"
}
},
"ts_ms": 1705318200125,
"ts_ns": 1705318200125483291
}
```
**Record di frammenti**
Ogni frammento è il proprio record Kinesis `type` con set `fragment` to e tre campi`chunk_id`: corrisponde al valore nel record `chunked.before.chunk_id` corrispondente `chunked.after.chunk_id` o nel record principale`index`, è la posizione in base zero del frammento all'interno dell'immagine `data` ed è un segmento del testo JSON dell'immagine suddiviso UTF-8 sui limiti dei caratteri (il valore di ogni frammento `data` è una stringa valida a sé stante). UTF-8 Poiché Aurora DSQL CDC utilizza la `UNORDERED` modalità e le chiavi di partizione randomizzate, i frammenti e il record principale possono arrivare su diversi shard e in qualsiasi ordine. Per leggere tutti i frammenti, utilizza tutti gli shard del flusso di dati Kinesis. Per ulteriori informazioni sugli ordini con consegna, consulta. [Ordinazione](cdc-streams.md#cdc-ordering)
```
{
"type": "fragment",
"chunk_id": "{{chunk-id}}",
"index": 0,
"data": "{{partial-JSON-text}}"
}
```
Per riassemblare un'immagine sovradimensionata, inserite nel buffer ogni record con il relativo. `type` `fragment` `chunk_id` Quando ricevete un record principale con `type``chunked`, attendete di avere `total_fragments` frammenti per ogni `chunk_id` riferimento sotto `chunked.before` o`chunked.after`, ordinate i frammenti in ordine crescente e concatenate le stringhe. `index` `data` Il risultato concatenato è l'originale `before` o `after` l'oggetto come testo JSON: analizzatelo per accedere ai valori delle colonne. Per verificare l'integrità della consegna, calcola CRC32C sulla stringa concatenata e confronta il risultato con o. `chunked.before.crc32c` `chunked.after.crc32c`
## Serializzazione del tipo di dati
Le tabelle seguenti descrivono come Aurora DSQL serializza ogni tipo di dati PostgreSQL nei record CDC.
### Tipi Integer
| Tipo PostgreSQL | Rappresentazione JSON | Esempio |
| --- |--- |--- |
| smallint (int2) | Numero JSON | 42 |
| integer (int4) | Numero JSON | 1001 |
| bigint (int8) | Numero JSON | 9223372036854775807 |
| oid | Numero JSON (senza segno) | 16384 |
I valori `bigint` superiori a ±2^53 potrebbero perdere la precisione negli ambienti. JavaScript In questi casi, utilizzate BigInt librerie a precisione arbitraria.
### Floating-point tipi
| Tipo PostgreSQL | Rappresentazione JSON | Esempio | Note |
| --- |--- |--- |--- |
| real (float4) | Numero JSON | 3.14159 | NaN e ±Infinity sono serializzati come stringhe"NaN",,. "Infinity" "-Infinity" |
| double precision (float8) | Numero JSON | 3.141592653589793 | Stessa gestione dei valori speciali direal. |
| numeric / decimal | Stringa JSON | "123.45" | Sempre una stringa per preservare la precisione esatta. NaN e ±Infinity sono serializzati come stringhe"NaN",,. "Infinity" "-Infinity" |
### Booleano
| Tipo PostgreSQL | Rappresentazione JSON | Esempio |
| --- |--- |--- |
| boolean | JSON booleano | true o false |
### Tipi di carattere
| Tipo PostgreSQL | Rappresentazione JSON | Esempio |
| --- |--- |--- |
| varchar / text | stringa JSON | "Hello, world\!" |
| bpchar (char(n)) | stringa JSON | "ABC"(spazi finali eliminati) |
| name | stringa JSON | "pg\_class" |
| "char"(byte singolo) | stringa JSON | "A" |
### Binario
| Tipo PostgreSQL | Rappresentazione JSON | Esempio |
| --- |--- |--- |
| bytea | stringa JSON (Base64) | "SGVsbG8gV29ybGQh" |
### Tipi di data e ora
| Tipo PostgreSQL | Rappresentazione JSON | Esempio | Note |
| --- |--- |--- |--- |
| date | Numero JSON (giorni dall'epoca di Unix) | 19797 | \+infinitye -infinity sono rappresentati come conteggi dei giorni sentinella derivati dall'aritmetica epoch-offset. Questi valori non corrispondono a date di calendario significative. |
| time | Numero JSON (microsecondi dalla mezzanotte) | 52200123456 | |
| timetz | Numero JSON (microsecondi dalla mezzanotte, UTC) | 52200123456 | L'ora locale viene adattata all'UTC applicando lo scostamento del fuso orario memorizzato (secondi a ovest dell'UTC). Il risultato viene riassunto nell'intervallo [0, 86400000000) microsecondi. |
| timestamp | Numero JSON (microsecondi dall'epoca Unix) | 1710510600123456 | ±Infinity esegue la mappatura ai valori sentinella: for e for. 9223372036825200000 \+infinity -9223372036832400000 -infinity |
| timestamptz | Numero JSON (microsecondi dall'epoca Unix) | 1710510600123456 | Memorizzato ed emesso in UTC. Stessi valori di sentinella ±infinity di. timestamp |
| interval | Numero JSON (microsecondi totali approssimativi) | 2802603000000 | I mesi sono approssimativamente pari a 30,4375 giorni (2.629.800 secondi). Il totale (months × 2,629,800 \+ days × 86,400) × 1,000,000 \+ microseconds viene calcolato come. Se il risultato supera l'intervallo di numeri interi con segno a 64 bit (±9.223.372.036.854.775.807 microsecondi, circa ±292.271 anni), Aurora DSQL emette JSON per la colonna. null |
### Altri tipi
| Tipo PostgreSQL | Rappresentazione JSON | Esempio |
| --- |--- |--- |
| uuid | Stringa JSON (formato esadecimale standard 8-4-4-4-12) | "550e8400-e29b-41d4-a716-446655440000" |
| oidvector | Matrice vuota JSON | [] |
| json | Stringa JSON contenente il testo JSON non elaborato | "{\\"key\\": \\"value\\"}" |
### Valori NULL
Per qualsiasi tipo di dati, i valori `NULL` delle colonne sono rappresentati come `null` JSON.
## Evoluzione dello schema nei record CDC
Quando si modifica lo schema di una tabella, ad esempio aggiungendo, eliminando o rinominando una colonna, i record CDC riflettono la modifica a partire dalla transazione che ha eseguito la modifica DDL. I record delle transazioni eseguite prima della modifica DDL utilizzano lo schema precedente. Esempio:
+ Se aggiungi una colonna, i record delle transazioni precedenti non includono la nuova colonna. I record dalla transazione di aggiunta in poi includono la nuova colonna.
+ Se si elimina una colonna, i record dalla transazione di eliminazione in poi non includono più quella colonna.
+ Se si rinomina una colonna, i record dalla transazione di ridenominazione in poi utilizzano il nuovo nome di colonna.
Tieni traccia delle modifiche allo schema nel tuo consumatore a valle esaminando i nomi delle colonne presenti in ogni record e campo. `after` `before` Il `source.version` campo in ogni record identifica il formato della busta CDC.