Skip to main content

"recordPath"

Specifies the location in a record where the server reads or writes a JSON value

The "recordPath" property specifies the location in a record where the server reads or writes a JSON value. It specifies a field name followed by an optional JSONPath. Depending on the context, it refers to a value the server reads or writes. 

For example, in the "tableFieldsToJson" transform method, "recordPath" is the location where the transform step writes a transformed value. In the "jsonToTableFields" and "jsonToDifferentTableFields" transform methods, "recordPath" is the location where the transform step reads the value that it transforms.

  • The "recordPath" property must always include a field name.

    • The server returns an error when the field name is missing or does not exist.

  • The "recordPath" property may include a JSONPath after the field name.

    • If no JSONPath follows the field, the "recordPath" property refers to the entire field, and the field is not required to contain a JSON document.

    • If a JSONPath follows the field, the "recordPath" property refers to a part of the JSON document inside the field.

Several FairCom APIs, such as the DB and Transform APIs, treat each record in each table as a JSON document. The top-level fields in the record are treated as top-level properties in the JSON document. In other words, you can think of each record as a JSON document, and you can use the "recordPath" property to refer to any field in the record and any JSON property or array item within a JSON field.

When the server writes a value to a "recordPath", it looks for the specified field and JSONPath and does the following:

  • If the specified field does not exist, the server returns an error.

  • If the JSONPath is not specified after the fieldname, the server writes the value directly to the field.

  • If the field's value does not contain a JSON document, the server returns an error.

  • If the JSONPath specifies a property or array item that does not exist in the field's JSON document, the server adds it.

  • If the JSONPath specifies a property or array item that already exists in the field's JSON document, the server replaces the old value.

When the server reads a value from a "recordPath", it looks for the specified field and JSONPath and does the following:

  • If the specified field does not exist, the server returns an error.

  • If the JSONPath is not specified after the fieldname, the server reads the entire field value.

  • If the field's value does not contain a JSON document, the server returns an error.

  • If the JSONPath specifies a property or array item that does not exist in the field's JSON document, the server returns null because FairCom's data model treats a missing JSON property the same as one assigned to null.

  • If the JSONPath specifies a property or array item that already exists in the field's JSON document, the server replaces the old value.

Note

Unlike "propertyPath", a "recordPath" includes the name of the field that contains the JSON document.

Simple "recordPath" example

For example, a JSONPath of "temperature" refers to a field named "temperature".

Example record in an integration Table

The following record contains three fields: id, source_payload, and create_ts.

Table 1. record in an integration table

id

source_payload

create_ts

1

{
  "humidity": 
  [
    {
      "temperature": 20.1,
      "pressure": 1003
    }
  ]
}

"2025-07-07T14:14:02.012"



JSON representation of the example record

The following JSON is how the JSON DB and Transform APIs represent the previous record. The top level properties are fields in the integration table.

{
  "id": 1,
  "source_payload": 
  {
    "humidity": 
    [
      {
        "temperature": 20.1,
        "pressure": 1003
      }
    ]
  },
  "create_ts": "2025-07-07T14:14:02.012"
}

"recordPath" properties for each value in the example record

Table 2. "recordPath" properties

"recordPath"

Field Value

"recordPath": "id"

1

"recordPath": "source_payload"

{
  "humidity": 
  [
    {
      "temperature": 20.1,
      "pressure": 1003
    }
  ]
}

"recordPath": "source_payload.humidity"

[
  {
    "temperature": 20.1,
    "pressure": 1003
  }
]

"recordPath": "source_payload.humidity[0]"

{
  "temperature": 20.1,
  "pressure": 1003
}

"recordPath": "source_payload.humidity[0].temperature"

20.1

"recordPath": "source_payload.humidity[0].pressure"

1003

"recordPath": "create_ts"

"2025-07-07T14:14:02.012"



The required "recordPath" property specifies the location of a JSON property in a record. It starts with the name of a field in the table followed by an optional JsonPath to a JSON property within that field.

The "recordPath" property specifies the exact location within a database record where a JSON value should be read from or written to, acting as a pointer that always includes a field name and can optionally be followed by a JSONPath to navigate within a JSON document stored in that field. Unlike "propertyPath", it implicitly starts at the record level, treating each record's top-level fields as JSON properties. When writing, it will create or replace JSON properties as needed within the designated field; when reading, it will retrieve the value or return null if the specified path within a JSON field does not exist, and it will return an error if the initial field name is missing or the field itself doesn't contain a JSON document when a JSONPath is used.

recordPath JSON
JSONPath recordPath
edit recordPath
configure recordPath
customize recordPath
access JSON in database records
read write JSON record value
DB API recordPath
transform API recordPath
how to use recordPath
specify JSON location in record