Journalexportausgabe in QLDB

Ein Amazon QLDB-Journal-Exportjob schreibt zusätzlich zu den Datenobjekten, die Ihre Journalblöcke enthalten, zwei Manifestdateien. Diese werden alle in dem Amazon S3 S3-Bucket gespeichert, den Sie in Ihrer Exportanfrage angegeben haben. Die folgenden Abschnitte beschreiben das Format und den Inhalt der einzelnen Ausgabeobjekte.

Anmerkung

Wenn Sie JSON als Ausgabeformat für Ihren Exportauftrag angeben, konvertiert QLDB die Amazon Ion-Journaldaten in Ihren exportierten Datenobjekten nach JSON herunter. Weitere Informationen finden Sie unter. Abwärtskonvertierung nach JSON

Manifestdateien

Amazon QLDB erstellt für jede Exportanfrage zwei Manifestdateien im bereitgestellten S3-Bucket. Die ursprüngliche Manifestdatei wird erstellt, sobald Sie die Exportanforderung übermitteln. Die finale Manifestdatei wird geschrieben, nachdem der Exportvorgang abgeschlossen ist. Sie können diese Dateien verwenden, um den Status Ihrer Exportaufträge in Amazon S3 zu überprüfen.

Das Format für den Inhalt der Manifestdateien entspricht dem angeforderten Ausgabeformat für den Export.

Erstes Manifest

Die ursprüngliche Manifestdatei gibt an, dass Ihr Exportauftrag gestartet wurde. Sie enthält die Eingabeparameter, die Sie der Anforderung übergeben haben. Neben dem Amazon S3 S3-Ziel und den Start- und Endzeitparametern für den Export enthält diese Datei auch eineexportId. Das exportId ist eine eindeutige ID, die QLDB jedem Exportauftrag zuweist.

Die Benennungskonvention für die Datei lautet wie folgt.

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.started.manifest

Im Folgenden finden Sie ein Beispiel für eine erste Manifestdatei und ihren Inhalt im Ion-Textformat.

s3://DOC-EXAMPLE-BUCKET/journalExport/8UyXulxccYLAsbN1aon7e4.started.manifest

{
  ledgerName:"my-example-ledger",
  exportId:"8UyXulxccYLAsbN1aon7e4",
  inclusiveStartTime:2019-04-15T00:00:00.000Z,
  exclusiveEndTime:2019-04-15T22:00:00.000Z,
  bucket:"DOC-EXAMPLE-BUCKET",
  prefix:"journalExport",
  objectEncryptionType:"NO_ENCRYPTION",
  outputFormat:"ION_TEXT"
}

Das erste Manifest enthält outputFormat nur dann, wenn es in der Exportanforderung angegeben wurde. Wenn Sie das Ausgabeformat nicht angeben, wird für die exportierten Daten standardmäßig das ION_TEXT Format Format verwendet.

Der DescribeJournalS3Export API-Vorgang und der Inhaltstyp der exportierten Amazon S3 S3-Objekte geben auch das Ausgabeformat an.

Endgültiges Manifest

Das finale Manifest gibt an, dass Ihr Exportauftrag für eine bestimmte Journal-Strähne abgeschlossen ist. Der Exportauftrag schreibt eine separate finale Manifestdatei für jeden Strähne.

Anmerkung

In Amazon QLDB ist ein Strang eine Partition des Tagebuchs Ihres Hauptbuches. QLDB unterstützt derzeit nur Zeitschriften mit einem einzigen Strang.

Die finale Manifestdatei enthält eine geordnete Liste der Daten- Objektschlüssel, die während des Exportvorgangs geschrieben wurden. Die Benennungskonvention für die Datei lautet wie folgt.

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.strandId.completed.manifest

Das strandId ist eine eindeutige ID, die QLDB dem Strang zuweist. Im Folgenden finden Sie ein Beispiel für eine endgültige Manifestdatei und ihren Inhalt im Ion-Textformat.

s3://DOC-EXAMPLE-BUCKET/journalExport/8UyXulxccYLAsbN1aon7e4.JdxjkR9bSYB5jMHWcI464T.completed.manifest

{
  keys:[
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-4.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.5-10.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.11-12.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.13-20.ion",
    "2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.21-21.ion"
  ]
}

Datenobjekte

Amazon QLDB schreibt Journaldatenobjekte in den bereitgestellten Amazon S3 S3-Bucket entweder in der Text- oder Binärdarstellung des Amazon Ion-Formats oder im JSON Lines-Textformat.

Im Format JSON Lines ist jeder Block in einem exportierten Datenobjekt ein gültiges JSON-Objekt, das durch eine neue Zeile begrenzt ist. Sie können dieses Format verwenden, um JSON-Exporte direkt in Analysetools wie Amazon Athena zu integrieren, und AWS Glue weil diese Dienste JSON mit Zeilenumbrüchen automatisch analysieren können. Weitere Informationen zum Format finden Sie unter JSON-Zeilen.

Datenobjektnamen

Ein Journalexportauftrag schreibt diese Datenobjekte mit der folgenden Benennungskonvention.

s3://DOC-EXAMPLE-BUCKET/prefix/yyyy/mm/dd/hh/strandId.startSn-endSn.ion|.json

• Die Ausgabedaten der einzelnen Exportaufträge sind in Datenblöcke aufgeteilt.

• yyyy/mm/dd/hh— Datum und Uhrzeit der Einreichung der Exportanfrage. Objekte, die innerhalb derselben Stunde exportiert werden, werden unter demselben Amazon S3 S3-Präfix gruppiert.

• strandId— Die eindeutige ID des jeweiligen Strangs, der den Journalblock enthält, der exportiert wird.

• startSn-endSn— Der Sequenznummernbereich, der im Objekt enthalten ist. Eine Sequenznummer gibt die Position eines Blocks innerhalb eines Strangs an.

Nehmen Sie zum Beispiel an, dass Sie den folgenden Pfad angeben.

s3://DOC-EXAMPLE-BUCKET/journalExport/

Ihr Exportauftrag erstellt ein Amazon S3 S3-Datenobjekt, das dem Folgenden ähnelt. Dieses Beispiel zeigt einen Objektnamen im Ion-Format.

s3://DOC-EXAMPLE-BUCKET/journalExport/2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-5.ion

Inhalt des Datenobjekts

Jedes Datenobjekt enthält Journalblockobjekte mit dem folgenden Format.

{
  blockAddress: {
    strandId: String,
    sequenceNo: Int
  },
  transactionId: String,
  blockTimestamp: Datetime,
  blockHash: SHA256,
  entriesHash: SHA256,
  previousBlockHash: SHA256,
  entriesHashList: [ SHA256 ],
  transactionInfo: {
    statements: [
      {
        //PartiQL statement object
      }
    ],
    documents: {
      //document-table-statement mapping object
    }
  },
  revisions: [
    {
      //document revision object
    }
  ]
}

Ein Block ist ein Objekt, das während einer Transaktion im Journal festgeschrieben wird. Ein Block enthält Transaktionsmetadaten zusammen mit Einträgen, die die Dokumentrevisionen darstellen, die in der Transaktion festgeschrieben wurden, sowie die PartiQL-Anweisungen, die diese festgeschrieben haben.

Im Folgenden finden Sie ein Beispiel für einen Block mit Beispieldaten im Ion-Textformat. Weitere Informationen zu den Feldern in einem Blockobjekt finden Sie unter Journalinhalte in Amazon QLDB.

Anmerkung

Dieses Blockbeispiel dient nur zu Informationszwecken. Die angezeigten Hashes sind keine echten berechneten Hashwerte.

{
  blockAddress:{
    strandId:"JdxjkR9bSYB5jMHWcI464T",
    sequenceNo:1234
  },
  transactionId:"D35qctdJRU1L1N2VhxbwSn",
  blockTimestamp:2019-10-25T17:20:21.009Z,
  blockHash:{{WYLOfZClk0lYWT3lUsSr0ONXh+Pw8MxxB+9zvTgSvlQ=}},
  entriesHash:{{xN9X96atkMvhvF3nEy6jMSVQzKjHJfz1H3bsNeg8GMA=}},
  previousBlockHash:{{IAfZ0h22ZjvcuHPSBCDy/6XNQTsqEmeY3GW0gBae8mg=}},
  entriesHashList:[
      {{F7rQIKCNn0vXVWPexilGfJn5+MCrtsSQqqVdlQxXpS4=}},
      {{C+L8gRhkzVcxt3qRJpw8w6hVEqA5A6ImGne+E7iHizo=}}
  ],
  transactionInfo:{
    statements:[
      {
        statement:"CREATE TABLE VehicleRegistration",
        startTime:2019-10-25T17:20:20.496Z,
        statementDigest:{{3jeSdejOgp6spJ8huZxDRUtp2fRXRqpOMtG43V0nXg8=}}
      },
      {
        statement:"CREATE INDEX ON VehicleRegistration (VIN)",
        startTime:2019-10-25T17:20:20.549Z,
        statementDigest:{{099D+5ZWDgA7r+aWeNUrWhc8ebBTXjgscq+mZ2dVibI=}}
      },
      {
        statement:"CREATE INDEX ON VehicleRegistration (LicensePlateNumber)",
        startTime:2019-10-25T17:20:20.560Z,
        statementDigest:{{B73tVJzVyVXicnH4n96NzU2L2JFY8e9Tjg895suWMew=}}
      },
      {
        statement:"INSERT INTO VehicleRegistration ?",
        startTime:2019-10-25T17:20:20.595Z,
        statementDigest:{{ggpon5qCXLo95K578YVhAD8ix0A0M5CcBx/W40Ey/Tk=}}
      }
    ],
    documents:{
      '8F0TPCmdNQ6JTRpiLj2TmW':{
        tableName:"VehicleRegistration",
        tableId:"BPxNiDQXCIB5l5F68KZoOz",
        statements:[3]
      }
    }
  },
  revisions:[
    {
      hash:{{FR1IWcWew0yw1TnRklo2YMF/qtwb7ohsu5FD8A4DSVg=}}
    },
    {
      blockAddress:{
        strandId:"JdxjkR9bSYB5jMHWcI464T",
        sequenceNo:1234
      },
      hash:{{t8Hj6/VC4SBitxnvBqJbOmrGytF2XAA/1c0AoSq2NQY=}},
      data:{
        VIN:"1N4AL11D75C109151",
        LicensePlateNumber:"LEWISR261LL",
        State:"WA",
        City:"Seattle",
        PendingPenaltyTicketAmount:90.25,
        ValidFromDate:2017-08-21,
        ValidToDate:2020-05-11,
        Owners:{
          PrimaryOwner:{
            PersonId:"GddsXfIYfDlKCEprOLOwYt"
          },
          SecondaryOwners:[]
        }
      },
      metadata:{
        id:"8F0TPCmdNQ6JTRpiLj2TmW",
        version:0,
        txTime:2019-10-25T17:20:20.618Z,
        txId:"D35qctdJRU1L1N2VhxbwSn"
      }
    }
  ]
}

Im revisions-Feld enthalten einige Revisionsobjekte möglicherweise nur einen hash-Wert und keine anderen Attribute. Dabei handelt es sich um interne Systemrevisionen, die keine Benutzerdaten enthalten. Ein Exportauftrag enthält diese Revisionen in den jeweiligen Blöcken, da die Hashes dieser Revisionen Teil der vollständigen Hashkette des Journals sind. Die vollständige Hashkette ist für die kryptografische Verifizierung erforderlich.

Abwärtskonvertierung nach JSON

Wenn Sie JSON als Ausgabeformat für Ihren Exportauftrag angeben, konvertiert QLDB die Amazon Ion-Journaldaten in Ihren exportierten Datenobjekten nach JSON herunter. Die Konvertierung von Ion in JSON ist jedoch in bestimmten Fällen, in denen Ihre Daten umfangreiche Ion-Typen verwenden, die es in JSON nicht gibt, mit Verlusten verbunden.

Einzelheiten zu den Regeln für die Konvertierung von Ion in JSON finden Sie unter Down-Converting to JSON im Amazon Ion Cookbook.

Prozessorbibliothek exportieren (Java)

QLDB bietet ein erweiterbares Framework für Java, das die Verarbeitung von Exporten in Amazon S3 optimiert. Diese Framework-Bibliothek übernimmt das Lesen der Ausgabe eines Exports und das Durchlaufen der exportierten Blöcke in sequentieller Reihenfolge. Informationen zur Verwendung dieses Exportprozessors finden Sie im GitHub Repository amazon-qldb-export-processorawslabs/ -java.