Format transformations

Format transformations allow you to rename fields, ignore fields, or cast values to new data types. Each format transformation uses this syntax:

<field-name>[->new-name]:<field-type>[(date_format)],...
Element Required Description

field-name

Required

The name of the field that exists in source documents.

new-name

Optional

The new name of this field in the database. This provides the ability to rename fields.

The -> prefix is required to perform renames.

field-type

Optional

Tells the loader what data type to load the field as. See Support types below.

(date_format)

Optional

An optional date format string argument to field-type. The date and ts/timestamp types can accept a date format string argument that determines which portions of the field value to express in the destination document.

For example, if the source document’s field called timestamp contains the timestamp value 2020-04-09T12:34:56, the format transformation timestamp:ts(yyyy-MM-dd) causes only the year, month, and day portions of the timestamp when creating the field value in the destination document.

With the date type, the destination document’s field value is always a FaunaDB Date type (no time information is included). With the ts/timestamp type, the destination document’s field value is always a FaunaDB Timestamp type, even if the date_format is only configured to express the date portions of a timestamp.

See Class SimpleDateFormat for details on the date format specification.

Supported field types

The field type names are case sensitive and allow you to check that the data is loaded into the requested type. If the conversion can not be made then a default value is placed in the load and no error is emitted.

Type Description

boolean

Attempt to convert the field value to a boolean. Booleans map naturally; integer numbers other than 0 convert to true and 0 converts to false, and the Strings true and false convert to their boolean equivalents.

long

Attempt to convert the field value to a long (a 64-bit, two’s complement integer) . Numbers are coerced using default Java rules; booleans convert to 0 (false) and 1 (true), and Strings are parsed using default Java language integer parsing rules.

double

Attempt to convert the field value to a double (a double-precision, 64-bit floating point number). Numbers are coerced using default Java rules; booleans convert to 0.0 (false) and 1.0 (true), and Strings are parsed using default Java language integer parsing rules.

number

Attempt to convert the field value to a long (a 64-bit, two’s complement integer) if possible, otherwise convert to a double (a double-precision, 64-bit floating point number).

string

Attempt to convert the field value to a string. Empty or null values convert to the empty string.

date

Attempt to convert the field value to a date.

ts or timestamp

Attempt to convert the field value to a timestamp.

ignore

Omit this field from the destination document.

ID or REF

Use this field’s value as the id for the destination document’s reference. If this field name is found in the source document and this field is a long value (a 64-bit, two’s complement integer), then this field is used as the destination document’s reference id. If this value is not set then the destination document’s reference id is automatically generated.

TS

Use this field’s value as the document’s creation time, and remove this field from the document.

If this field name is found in the data to be loaded, then this field value is used as the time this document was created. If this field is not found, or an incorrect format is found, then this document’s timestamp is set to the current time.

The format of the field value with the TS type must match the current timestamp format. The default format is: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

Example: mytimestamp_field:TS

Rename a field

To rename a field, use the format parameter and provide both the current field name and the new field name, separated by an arrow ->: current_field_name->new_field_name

For example, when a source document contains a field called power_usage but you want the destination document field to have the name used_power, you would specify the following format transformation: power_usage->used_power

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!