Rockset Extended JSON

Rockset supports an extended version of the JSON format which allows for Rockset specific types that are not supported by JSON. This format is used for both query parameters and ingestion.

JSON Format

Rockset supports many different data types but by default values will be parsed as standard JSON so the value "hello" will be parsed as a string. A numeric type will be parsed as an int if it falls within the range of the int data type and does not contain a floating point or exponent. Otherwise, the value will be read as a float.

Extended Format

There are many types that Rockset supports that are not JSON native such as
u256 along with
Date and Time types. To support the interpretation of these types, we wrap them in a JSON object containing a special key "__rockset_type" which points to the string value of the desired type that will be used to parse the value pointed to by the special "value" key.

For example, the following JSON object will be interpreted as a value of 10 with type u256:

{
   "__rockset_type": "u256",
    "value": "10"
}

Like value there are a few special keys outside of rockset_type but only _rocksettype will be used to check for the presence of a special typed value. Otherwise these object fields will be read in as part of normal JSON objects.

Special keys

__rockset_type

Required in order to specify a typed value. Supports all Rockset data types which means in some cases, like integer parsing, it can be used to override the inferred JSON type.

value

Required string that specifies the value which will be parsed as the requested
__rockset_type.

format

This field is optional and specifies the format to be used when parsing a Date or Time type. If not specified the default ISO-8601 format for that type will be used. You can lean more about date formatting and Rockset here```

timezone

This field is optional and specifies the TZ identifier that will be used to parse a timestamp type. By default 'UTC' will be used.

encoding

A required field for the bytes data type. Only "base64" is currently supported.

Examples

Value of type DATE using a custom format.

{
    "__rockset_type": "date",
    "value": "2023-01-01",
    "format": "YYYY-[M]M-[D]D"
}

Value of type TIMESTAMP using a custom format and a special timezone.

{
    "__rockset_type": "timestamp",
    "value": "2018-01-01 09:30:45.456-05:00",
    "format": "YYYY-[M]M-[D]D[( |T)[H]H:[M]M:[S]S[.DDDDDD]][time zone]",
    "timezone": "America/Cancun"
}

Value of type float that would have looked like an integer to a JSON parser.

{
   "__rockset_type": "float",
   "value": "10"
}

No special Rockset typing just a nested object value.

{
    "anyArray": ["float", 1, 5, null],
    "someOtherValue": {
        "nestedVal": "example value"
    }
}