Datatypes in Lucy

This section explains the various types of data your models can receive and send out. These are not related to attribute data types, which are different. Here, we are talkinga about the types of data that flows through the blocks and their inputs and outputs.

Broadly speaking, these are the types of data you can see:

  1. Text
  2. Numbers
  3. DateTimes
  4. Dictionaries
  5. JSON
  6. Result Sets
  7. Arrays
  8. Binary
  9. Null

Text Data

Text data is the most common form of data you will use and see. All text is UTF-8 encoded. Most blocks that accept numeric values will also accept textual representations of them. When you hard-code a value for an input to a block, it is always as text.

In Javascript blocks, these are available as regular javascript strings.

Numeric Data

Numeric data could either be integers, floating point values or double-precision values. In Javascript blocks these are available as Javascript Number types

DateTimes

DateTimes represent timestamps - a combination of a date and a time. These are generated by Lucy in UTC and it’s encouraged that you send UTC everywhere as well. In Javascript blocks these are available as regular Javascript Date objects.

See Working with Dates and Times for more information.

Dictionaries

Dictionaries are key/value pairs where the key is a string and the value is any other data type. In Javascript blocks, these are converted to Javascript Objects.

See Dictionaries and Objects for more information about them.

JSON

JSON types represent _parsed_ json objects. They can be objects or arrays or values. These are typically output from a block that parses text into JSON.

Most of the JSON blocks in Lucy except a JSON value to be passed in. However, many also accept a textual representation of the JSON.

In Javascript blocks, these are available as regular Javascript Objects.

JSON can typically be used in all the places where dictionaries are expected.

Result Sets

Result Sets are essentially a list of dictionaries, with all dictionaries having the same set keys. You can think of it as a table of data - each row is a dictionary with the columns as keys.

They can be used as an array when feeding to a repeater or any block that takes a list of items.

When sent as an input to Javascript blocks these are converted into an array of Javascript objects.

Javascript code cannot create these result sets.

Arrays

Arrays represent a list of values with values within it being any supported data type. These can be fed into any block that takes a list of items - like a repeater block. Javascript blocks convert these into Javascript arrays internally.

Binary Data

See binobjects for more information about working with binary data

Null Data

These values are used where no value was present. These are converted to null in Javascript blocks. When an output pin has a null value, it will typically not be fed into the next block.

Dictionaries and Objects

Dictionaries are how Lucy internally represents sets of key/value pairs. Key/value pairs are the most common way of passing data around - whether as inputs to an action or event or for reading data from an external source. Dictionaries are implemented as an internal object in Lucy. Dictionaries can be created by

  • Using a Convert JSON block to parse a simple JSON object of the form
{"key1":"value1","key2":"value2",etc...}
  • Creating a javascript object within a Javascript block. Javascript objects are automatically converted to Lucy dictoinaries
  • Reading the All Output pin from an Action Start block.
  • Using a |mergedata| block to create a new dictionary or to add data to an existing dictionary

Working with Dates and Times

In Lucy dates, times and timestamps are stored internally in a special format that makes it easy to manipulate using standard date time functions. However, there are some things to be aware of.

Working with Timezones

All date/time values in Lucy are stored and represented in UTC format. They are converted to other time zones only for display purposes. You can convert date/time value between time zones using the date and time functions provided by the Javascript block.

Timezones need to be specified using their internal iviva code.

The full list of timezones and their codes are available here: Time Zone Codes

Formatting dates and times for display

Supported date and time formats

Lucy can recognize four date/time formats:

  • ISO 8601 - see https://en.wikipedia.org/wiki/ISO_8601 for more details
  • yyyyMMdd
  • yyyyMMdd:HHmmss
  • yyyyMMdd HH:mm:ss

Working with Binary Data

You can pass around binary data in action sequences by creating a binary data object. A binary data object encapsulates binary data along with an optional content/type to identify it as well as an optional filename. You can create a binary data object by using a Javascript block.

You can use the oi.parseDataUri or oi.fromBase64 or oi.binaryBlobFromText functions to generate a binary data object from a data uri, from base64 encoded text or just normal utf-8 text.

In addition, the following functions also return binary data object data:

binary data object data can be passed around in blocks with inputs/outputs like other data. You can set it to Binary Output to let an action return binary data to the caller.

You can also save the data to the iviva storage system by calling oi.uploadData or oi.uploadDataWithExplicitName

Binary data objects encapsulate binary data to be passed around in action sequences in Lucy. They can be accessed by blocks as well as javascript. These objects contain the actual data as a byte array, an optional content-type and filename.