PartiQLIonSerde

PartiQL value is an experimental feature. This serde is not finalized and may contain bugs.

PartiQL Value <> ION

This section talks about Serialization and Deserialization between PartiQL Value and Ion Value.

Write To Ion Value

syntax shown in example column are for demostration purpose only

PartiQLValue Type	Ion Value Type	example
BOOL	BOOL	bool true -> true; false -> false
INT8	INT	int8 3 -> 3
INT16	INT	int16 314 -> 314
INT32	INT	int32 31415 -> 31415
INT64	INT	int64 314159265358 -> 314159265358
INT	INT	int 31415926535897932384 -> 31415926535897932384
DECIMAL	DECIMAL	decimal(3,2) 3.14 -> 3.14; decimal 3.1415925 -> 3.1415926
FLOAT32	FLOAT	buggy float32 0.33 -> 3.3e-1
FLOAT64	FLOAT	float64 0.33 -> 3.3e-1
CHAR	STRING	char 'a' -> "a"
STRING	STRING	string 'abc' -> "abc"
SYMBOL	SYMBOL	symbol "a" -> 'a'
BINARY	BLOB	binary {{'binary'}} -> {{YmluYXJ5}}
BYTE	BLOB	byte {'byte'} -> {{YQ==}}
BLOB	BLOB	blob {'blob'} -> {{YmxvYg==}}
CLOB	CLOB	clob {{'clob'}} -> {{"clob"}}
DATE	STRUCT	date '2023-01-01' -> $date::{year:2023, month:1, day: 1}
TIME	STRUCT	time '00:00:00.00' -> $time::{hour:0, minute: 0, second: 0.00}; time '00:00:00+00:00' -> $time::{hour: 0, minute: 0, second: 0., offset: 0}; time '00:00:00-00:00' -> $time::{hour: 0, minute: 0, second: 0., offset: null.int}
TIMESTAMP	STRUCT OR TIMESTAMP	timestamp '2023-01-01T00:00:00Z' -> 2023-01-01T00:00:00Z, timestamp '2023-01-01T00:00:00-00:00' -> 2023-01-01T00:00:00-00:00; `2023-01-01` -> 2023-01-01T00:00:00-00:00' timestamp '2023-01-01T00:00:00' -> $timestamp::{year:2023, month:1, day:1, hour:0, minute:0, second: 0.}
INTERVAL	TBD	TBD
BAG	LIST	<<1,2,3>> -> $bag::[1,2,3]
LIST	LIST	[1,2,3] -> [1,2,3]
SEXP	SEXP	sexp (1,2,3) -> (1,2,3)
STRUCT	STRUCT	{'a': 1} -> {a : 1}
NULL	NULL	null -> null.null
MISSING	NULL	missing -> $missing::null.null
NULLABLE_BOOL	BOOL	null -> null.bool else same as BOOL
NULLABLE_INT8	INT	null -> null.INT else same as INT8
NULLABLE_INT16	INT	null -> null.INT else same as INT16
NULLABLE_INT32	INT	null -> null.INT else same as INT32
NULLABLE_INT64	INT	null -> null.INT else same as INT64
NULLABLE_INT	INT	null -> null.INT else same as INT
NULLABLE_DECIMAL	DECIMAL	null -> null.DECIMAL else same as DECIMAL
NULLABLE_FLOAT32	FLOAT	null -> null.FLOAT else same as FLOAT32
NULLABLE_FLOAT64	FLOAT	null -> null.FLOAT else same as FLOAT64
NULLABLE_CHAR	STRING	null -> null.string else same as CHAR
NULLABLE_STRING	STRING	null -> null.string else same as STRING
NULLABLE_SYMBOL	SYMBOL	null -> null.symbol else same as SYMBOL
NULLABLE_BINARY	BLOB	null -> null.blob else same as BINARY
NULLABLE_BYTE	BLOB	null -> null.blob else same as BYTE
NULLABLE_BLOB	BLOB	null -> null.blob else same as BLOB
NULLABLE_CLOB	CLOB	null -> null.clob else same as CLOB
NULLABLE_DATE	STRUCT	null -> $date::null.struct else same as DATE
NULLABLE_TIME	STRUCT	null -> $time::null.struct else same as TIME
NULLABLE_TIMESTAMP	STRUCT OR TIMESTAMP	null -> null.timestamp else same as TIMESTAMP
NULLABLE_INTERVAL	TBD
NULLABLE_BAG	LIST	null -> $bag::null.list else same as BAG
NULLABLE_LIST	LIST	null -> null.list else same as LIST
NULLABLE_SEXP	SEXP	null -> null.sexp else same as SEXP
NULLABLE_STRUCT	STRUCT	null -> null.struct else same as STRUCT

Read From Ion Data

PartiQL reserves some keywords which are used as Ion annotations to extend the Ion types. To distinguish between generic Ion data and PartiQL data encoded as Ion, the reader has two modes: IonGeneric and IonForPartiQL.

Ion Generic

If using IonGeneric mode: The ion value annotations are always treated as annotations on PartiQL value.

For example: - $missing::null will be treated as nullValue(annotations = ["missing"])

Ion For PartiQL

When using IonForPartiQL mode, the last annotation is checked to see if this is an encoded PartiQL value. If the annotation is a PartiQL reserved keyword, then we validate and construct the PartiQL value.

For example:

• $missing::null will be treated as missingValue(annotations = [])
• a::b::$missing:null will be treated as missingValue(annotations = ["a", "b"])
• a::$missing::b::null will be treated as nullValue(annotation = ["a", "$missing", "b"]
• $missing::1 will cause an exception.