Amazon Ion data format reference in Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)
What is Amazon Ion?Ion specificationJSON compatibleExtensions from JSONIon text exampleAPI references

Amazon Ion data format reference in Amazon QLDB

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

Amazon QLDB uses a data notation model that unifies Amazon Ion with a subset of PartiQL types. This section provides a reference overview of the Ion document data format, separate from its integration with PartiQL.

Querying Ion with PartiQL in Amazon QLDB

For the syntax and semantics of querying Ion data with PartiQL in QLDB, see Querying Ion with PartiQL in the Amazon QLDB PartiQL reference.

For code examples that query and process Ion data in a QLDB ledger, see Amazon Ion code examples and Working with Amazon Ion.

Topics

What is Amazon Ion?

Ion is an open-source, richly typed, self-describing, hierarchical data serialization format that was originally developed internally at Amazon. It's based on an abstract data model that lets you store both structured and unstructured data. It's a superset of JSON, meaning that any valid JSON document is also a valid Ion document. This guide assumes a baseline working knowledge of JSON. If you aren't already familiar with JSON, see Introducing JSON for more information.

You can notate Ion documents interchangeably in either human-readable text form or binary-encoded form. Like JSON, the text form is easy to read and write, supporting rapid prototyping. The binary encoding is more compact and efficient to persist, transmit, and parse. An Ion processor can transcode between both formats to represent exactly the same set of data structures without any loss of data. This feature lets applications optimize how they process data for different use cases.

Note

The Ion data model is strictly value-based and doesn't support references. Thus, the data model can represent data hierarchies that can be nested to arbitrary depth, but not directed graphs.

Ion specification

For a full list of Ion core data types with complete descriptions and value formatting details, see the Ion specification document on the Amazon GitHub site.

To streamline application development, Amazon Ion provides client libraries that process Ion data for you. For code examples of common use cases for processing Ion data, see the Amazon Ion Cookbook on GitHub.

JSON compatible

Similar to JSON, you compose Amazon Ion documents with a set of primitive data types and a set of recursively defined container types. Ion includes the following traditional JSON data types:

  • null: A generic, untyped null (empty) value. Additionally, as described in the following section, Ion supports a distinct null type for each primitive type.

  • bool: Boolean values.

  • string: Unicode text literals.

  • list: Ordered heterogeneous collections of values.

  • struct: Unordered collections of name-value pairs. Like JSON, struct allows multiple values per name, but this is generally discouraged.

Extensions from JSON

Number types

Instead of the ambiguous JSON number type, Amazon Ion strictly defines numbers as one of the following types:

  • int: Signed integers of arbitrary size.

  • decimal: Decimal-encoded real numbers of arbitrary precision.

  • float: Binary-encoded floating point numbers (64-bit IEEE).

When parsing documents, an Ion processor assigns number types as follows:

  • int: Numbers with no exponent or decimal point (for example, 100200).

  • decimal: Numbers with a decimal point and no exponent (for example, 0.00001, 200.0).

  • float: Numbers with an exponent, such as scientific notation or E-notation (for example, 2e0, 3.1e-4).

New data types

Amazon Ion adds the following data types:

  • timestamp: Date/time/timezone moments of arbitrary precision.

  • symbol: Unicode symbolic atoms (such as identifiers).

  • blob: Binary data of user-defined encoding.

  • clob: Text data of user-defined encoding.

  • sexp: Ordered collections of values with application-defined semantics.

Null types

In addition to the generic null type defined by JSON, Amazon Ion supports a distinct null type for each primitive type. This indicates a lack of value while maintaining a strict data type.

null
null.null       // Identical to untyped null
null.bool
null.int
null.float
null.decimal
null.timestamp
null.string
null.symbol
null.blob
null.clob
null.struct
null.list
null.sexp

Ion text example

// Here is a struct, which is similar to a JSON object.
{
    // Field names don't always have to be quoted.
    name: "fido",
    
    // This is an integer.
    age: 7,
    
    // This is a timestamp with day precision.
    birthday: 2012-03-01T,
    
    // Here is a list, which is like a JSON array.
    toys: [
        // These are symbol values, which are like strings,
        // but get encoded as integers in binary.
        ball,
        rope
    ],
}

API references