Object Field data type

Home

4D v15

Starting with 4D v15, a new Object field type is supported by the 4D database engine.

Since 4D v14, you could already handle objects in your 4D applications but only through the language (see Objects (Language)). The Object field data type allows you to go further by:

storing objects in the data file,
adding, modifying or removing object attributes dynamically,
querying objects by attribute,
importing/exporting object values, etc.

Implementation Note: Some features do not currently support Object fields (see the Current limitations paragraph below).

Why use Object fields?

The Object field data type allows you to define schema-less dynamic fields. These Object fields can be considered as "user-defined" or "custom" fields. In 4D v15, you now have a choice between schema or schema-less data models. In both cases, you can execute fast indexed queries.

Also note that Object fields can simplify standard data models. For example, for a conventional "Contacts" table, a single Object field avoids the creation of dozens of fields representing every possible value - most of which are not used in 90% of cases. The information model is created on-the-fly only if required.

Object field definition

The new Object field data type can be set just like every other data type, using the Inspector of the Structure editor:

4D Object fields store attribute/value pairs of different kinds with no predefined data schema. The stored data structure is not necessarily the same between different records. For example, a [Person]Address Object field can contain different attributes depending on the city, the country, and so on:

record1= {"street1":"Cotton Treasure Grounds", "street2":"Place Corners", "state":"MD",...} 
record2= {"street1":"Umber Road", "Number":"28", "state":"MO",...}

The structure of 4D objects is based on the standard principle of "attribute/value" pairs. The syntax of these objects is based on JSON notation, but does not follow it entirely:

An attribute name is always a text, for example "Name".
An attribute value can be of the following types:
- number (Real, Integer, etc.)
- text
- array (text, Real, Longint, Integer, Boolean, object, pointer)
- null
- Boolean
- pointer (stored as such, evaluated using the JSON Stringify command or when copying),
- date ("YYYY-MM-DDTHH:mm:ssZ" format)
- object (objects can be nested on several levels).

Warning: Keep in mind that attribute names are case sensitive.

An Object field can be as large as 2 GB. When you are working with a record that contains an Object field, the entire object is loaded into memory. Just like Text, Picture or BLOB fields, Object fields can be stored in the data file (within records or not), or outside of the data file; this option is discussed in the External data storage section of the Design reference manual.

An Object field can be indexed (Automatic option only), which means that all attribute paths are automatically indexed. It can also be Invisible or have the Expose with 4D Mobile Service attribute. On the other hand, an Object field cannot be set as Unique.

You use 4D’s Objects (Language) commands to manage Object fields. Use the OB Get and OB SET commands to read and write data to and from Object fields. You can also store and read arrays as attributes using the OB SET ARRAY and OB GET ARRAY commands.

Since Object fields are text-based, the contents of an Object field are displayed in a 4D form by default as text and formatted in JSON (see the following section).

Note: To work with JSON objects, you can use the commands found in the "JSON" theme.

Displaying and entering object fields in forms

By default, Object fields are represented as text areas in 4D forms. Within these areas, object data must be either undefined, or formatted as JSON text; otherwise, an error is returned.

For example, if you have defined the [Rect]Desc field as an Object field, you can write:

 CREATE RECORD([Rect])

 [Rect]Name:="Blue square"

 OB SET([Rect]Desc;"x";"50";"y";"50";"color";"blue")

 SAVE RECORD([Rect])

If the [Rect]Desc field is included in your form, the following contents are displayed:

You can edit the displayed values directly in the text field, or enter object data directly using standard object notation; it will be formatted automatically in JSON when you press the [Tab] key:

However, direct editing must be carried out with precaution since any misplaced space or symbol will result in a JSON parsing error and the edited data will not be saved:

It is usually more accurate to handle the contents of Object fields using the Objects (Language) and JSON commands.

Getting and setting Object field values

All commands of the Objects (Language) theme now accept an Object field as first parameter (object).

Just like standard language objects, Object field values are handled using commands from the Objects (Language) theme. For example:

  // to set a value

 OB SET([Persons]Identity_OB;"First Name";$firstName)

 OB SET([Persons]Identity_OB;"Last Name";$lastName)

 

  // to get a value

 $firstName:=OB Get([Persons]Identity_OB;"First Name")

 $lastName:=OB Get([Persons]Identity_OB;"Last Name")

Arrays are supported as well, for example:

 ARRAY TEXT($arrGirls;3)

 $arrGirls{1}:="Emma"

 $arrGirls{2}:="Susan"

 $arrGirls{3}:="Jamie"

 OB SET ARRAY([Persons]Children;"Girls";$arrGirls)

Object field support in the 4D Language

The 4D language has been updated to support Object fields. In particular:

All commands from the Objects (Language) theme now support Object fields as first parameter (object)
A new command has been added to handle queries on Object fields: QUERY BY ATTRIBUTE. This command is detailed in a separate section.
SELECTION TO ARRAY, SELECTION RANGE TO ARRAY and ARRAY TO SELECTION commands support Object fields through ARRAY OBJECT bindings.
Selection to JSON and JSON TO SELECTION commands support Object fields, which are automatically converted to and from JSON.
Note however that the following 4D expression is ambiguous:
Selection to JSON([aTable];objectField)

could be interpreted as:
- produce JSON from all values of objectField in the current selection of the table
- produce JSON using the current record value of 'objectField' as a template
4D will behave as described in the first case because this is the most commonly used case.
Old and Modified commands support Object fields.
SET FIELD VALUE NULL clears Object field contents.
GET FIELD PROPERTIES can now return Is object.
PROCESS 4D TAGS supports Object fields in 4D formulas only.

Note however that for technical reasons, certain commands do not support Object fields. These commands are listed in the "Current limitations" section.

Formulas with Object fields

Object fields can be used in formulas (using the standard formula editor or the EXECUTE FORMULA command). However, in this context, Object fields can only be handled using the following commands:

For example, you can execute the following query formula:

OB Get([Rect]Desc;"color")="blue"

Current limitations

Most of 4D standard features support Object fields as any kind of data. However, some advanced parts of the application are not "Object field-ready" in the current release. These parts will be updated progressively and will become available to Object fields in upcoming releases.