Objects

Objects is a section that defines the objects and their fields in the GraphQL connector. It contains object configurations.

Object configurations contain the following settings:

For example,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
  {
  "Objects": [
    {
      "Name": "Boards",
      "Path": "query.boards",
      "PagingStrategy": {
        "Type": "PageNo",
        "StartIndex": 1,
        "PageSize": 100,
        "PageNoArgument": "page",
        "PageNoBasePathPosition": 0,
        "PageNoPath": "query.boards",
        "PageSizeArgument": "limit",
        "PageSizeBasePathPosition": 0,
        "PageSizePath": "query.boards",
        "TotalPageCountBasePathPosition": 0,
        "TotalPageCountPath": null,
        "TotalRowsBasePathPosition": 0,
        "TotalRowsPath": null,
        "HasMoreBasePathPosition": 0,
        "HasMorePath": null,
        "EndErrors": [
        ]
      },
      "Headers": [
        {
          "Key": "TestHeaderKey",
          "Value": "TestHeaderValue"
        }
      ],
      "RetrieveSingleOperation": {
        "Path": "query.boards",
        "Arguments": [
          {
            "ColumnName": "Id",
            "Argument": "ids",
            "Path": "query.boards",
            "BasePathPosition": 0
          }
        ]
      },
      "InsertOperation": {
        "Path": "mutation.create_board",
        "ReturningPath": "mutation.create_board",
        "ReturningStrategy": {
          "Type": "Row"
        },
        "BulkSize": 5
      },
      "DeleteOperation": {
        "Path": "mutation.delete_board",
        "ReturningPath": "mutation.delete_board.id",
        "BulkSize": 5
      },
      "Columns": [
        {
          "Name": "Id",
          "Path": "id",
          "DbType": "String",
          "Primary": true,
          "Createable": false,
          "Updateable": false,
          "DeletePath": "board_id",
          "FilterOperations": [
            {
              "Operation": "IN",
              "Argument": "ids",
              "BasePathPosition": 2
            }
          ]
        },
        {
          "Name": "Name",
          "Path": "name",
          "InsertPath": "board_name",
          "Creatable": true,
          "Required": true,
          "DbType": "String"
        },
        {
          "Name": "Description",
          "Path": "description",
          "Createable": true,
          "DbType": "String",
          "Length": 2147483647
        }
      ]
    }
  ]
}

General Settings

Name

The name of the object.

Path

The path to the array of object records in the GraphQL query. The object’s fields for the SELECT operation are appended to the last segment of this path. (required parameter).

Headers

The headers of the web request for reading the object. Specify Headers as a JSON array of objects with the Key and Value properties. These headers are merged with the respective constant headers, specified in ProviderConfiguration Headers section.

ConstantParameters

The constant parameters added to GraphQL Query/Mutation for reading the object. These constant parameters are merged with the respective constant parameters, specified in ProviderConfiguration ConstantParameters section.

PagingStrategy

This section defines the specific paging strategy for an object. Add this section if it differs from the ProviderConfiguration PagingStrategy

ErrorHandling

Determines the specific object behavior in case of errors. Add this section if the behavior differs from the general settings provided in ProviderConfiguration ErrorHandling section.

SortOperation

Determines the sorting parameters for the object. Add this section if it differs from the ProviderConfiguration SortOperation section.

Columns

This section contain configurations, which define connector object fields:

Name

The field name the user will see when querying the object data. For example, {"Name":"Amount"}.

Path

The relative path of the field in the GraphQL query. The base path for it is always the object’s Path. For example: "Path": "author.id". If we do not want to read the field from the results and the column is only needed to send an argument in DML operations, then this path should not be specified (instead, InsertPath/UpdatePath should be specified).

If the field value is nested within other properties, the Path specifies the path to the column in the format: <parent property name>.<property name>. The nesting level is unlimited.

Although unlikely, if a dot is part of the property name rather than a hierarchy separator, quoting with {} should be used. For example: Path: "{my.amount}"

For example, the source API returns the address in the following format:

1
2
3
4
5
6
7
8
9
10
{
   "address": {
    "country" : "USA",
    "city" : "New York",
    "contactInfo" : {
     "phone" : "1111",
     "fax" : "1111"
    }
  }
}

The corresponding fields in the corresponding object configuration should look like this:

1
2
3
4
{ "Name":"AddressCountry", "Path": "address.country",... }
{ "Name":"AddressCountry", "Path": "address.city",... }
{ "Name":"AddressPhone", "Path": "address.contactInfo.phone",... }
{ "Name":"AddressFax", "Path": "address.contactInfo.fax",... }

SingleResultPath

The relative path of the column in GraphQL for RetrieveSingleOperation. The base path for it is the Path of the operation in RetrieveSingleOperation.

InsertPath

Use this setting when the field path in the INSERT mutation differs from the Path for SELECT. The name or internal path of the GraphQL argument for the value of this field in InsertOperation. The base path for this argument is the Path of the InsertOperation.

UpdatePath

Use this setting when the field path in the UPDATE mutation differs from the Path for SELECT. The name or internal path of the GraphQL argument for the value of this field in UpdateOperation. The base path for this argument is the Path of the UpdateOperation.

DeletePath

Use this setting when the field path in the DELETE mutation differs from the Path for SELECT. The name or internal path of the GraphQL argument for the value of this field in DeleteOperation. The base path for this argument is the Path of the DeleteOperation.

ReturningPath

The relative path of the field in GraphQL for InsertOperation and UpdateOperation. The base path for this argument is the ReturningPath of the corresponding operation.

Use this setting when:

• ReturningStrategy is defined for an object or for the connector globally.
• The field path in the INSERT/UPDATE operation result differs from the path in SingleResultPath or Path.

Primary

Defines whether the field is the primary key or not. It accepts true and false values. Default value is false. Set Primary = true for every composite key field to define the composite primary key. We recommend specifying the primary key fields at the beginning of object configuration.

DbType

Defines the field data type. Default data type is String.

1
2
3
4
5
{
    "Name":"FirstName",
    "Path": "first_name",
    "DbType":"String"
}

The list of possible data types is the following:

SubType

Specifies the data type for complex JSON object or JSON array fields (having DbType set to JsonArray or JsonObject).

For JsonObject fields, it can be a name or complex type. For JsonArray fields, it can be the name of a complex type or the name of a simple data type, and it specifies the type of array elements.

If the SubType is not specified, the JSON field content is passed as is without further processing and mapping to a specific sub type fields structure.

Length

Number of characters for text type fields. Default values are: 38 for Guid, int.Maxvalue for JSON Object or JSON Array, 255 for other text types.

Precision

Max number of significant digits for a numeric field. For example,

1
2
3
4
5
6
7
{
    "Name": "Amount",
    "Path": "amount",
    "DbType": "Decimal",
    "Precision": 15,
    "Scale": 5
}

Scale

Number of characters after comma for numeric fields.

1
2
3
4
5
6
7
{
    "Name": "Amount",
    "Path": "amount",
    "DbType": "Decimal",
    "Precision": 15,
    "Scale": 5
}

TimeStampStoreMode

Use this setting to redefine the TimeStampStoreMode from the ProviderConfiguration section for the specific field.

For example,

1
2
3
4
5
6
{
    "Name": "AvailableOn",
    "Path": "available_on",
    "DbType": "DateTime",
    "TimeStampStoreMode": "SecondsSinceEpoch"
},

DateTimeFormat

This setting defines how to process the DateTime data. If you omit it, it inherits the DateTimeFormat value from the ProviderConfiguration section.

DateFormat

This setting defines how to process the Date data. If you omit it, it inherits the DateFormat value from the ProviderConfiguration section.

TimeFormat

This setting defines how to process the Time data. If you omit it, it inherits the TimeFormat value from the ProviderConfiguration section.

Nullable

This setting defines if the field can accept null values. Accepts true or false values. Default value is true.

Required

This setting defines whether the field is required or optional to fill in. Accepts true or false values. Default value false.

DMLKey

This setting defines if you can use this field in the WHERE condition of the UPDATE or DELETE operations to facilitate a record search and processing. Accepts true or false values.

Createable

Boolean setting, which defines if the field supports the INSERT operation. Accepts true or false values. Default value is True.

You must declare the InsertOperation section to use the INSERT operation.

Updatable

Boolean setting, which defines if this field supports the UPDATE operation. Accepts true or false values. Default value is True.

You must declare the UpdateOperation section to use the UPDATE operation.

DefaultValue

This setting defines the default value for the field.

1
2
3
4
5
6
{
    "Name": "Amount",
    "Path": "amount",
    "DbType": "Decimal",
    "DefaultValue": 0
}

NullAs

This setting defines a value the source uses as an empty value. This setting impacts the web requests for CRUD operations.

For example, some source uses "name": "" instead of "name": null. In this case, you specify "NullAs": "".

ExcludeNullValuesFromUpdate

Use this setting to omit fields with null values during the UPDATE operation. The connector will omit fields, for which null values are passed, in the request.

ExtendedRequest

Source API may return only part of the fields for some objects when querying multiple records. To query the values of lacking fields, Skyvia can perform additional extended requests for each record of such an object. However, this can decrease performance and significantly increase the number of API calls.

This setting defines whether it is necessary to perform such additional web requests by a record ID to get this field value for each record.

Skyvia performs additional requests only if at least one field with ExtendedRequest = true is present in the web request. If no fields with ExtendedRequest = true are selected in the request, then no additional requests exist.

Use this setting only if the RetrieveSingleOperation setting is determined for the object.

ExtendedRequest is boolean and accepts the true and false value. Default value is false.

Consider the source API limits when using this setting. We recommend using it to get data from really necessary or required fields.

CacheForInsert

Determines whether the field value should be stored for use in the RETURNING clause of the INSERT operation.

CacheForUpdate

Determines whether the field value should be stored for use in the RETURNING clause of the UPDATE operation. The primary key field is stored for RETURNING regardless of the value of this setting.

Enum

This setting defines if the field has a set of specific valid values. Enum and accepts True or False values.

Use this setting always together with EnumValues setting.

MultiEnum

This setting defines if the field is an array of specific valid values. MultiEnum accepts True or False values.

Use this setting always together with EnumValues setting.

EnumValues

This setting defines the set of specific valid values for the field if Enum or MultiEnum is true.
It is represented as key-value pairs: [{Name1:value1}, {Name2:value2}]. For example, the Status field valid values are: canceled, chargeable, consumed, failed.

The Columns setting for the Status field will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "Name": "Status",
    "Path": "status",
    "DbType": "String",
    "Enum": true,
    "EnumValues": [{
            "Name": "Canceled",
            "Value": "canceled"
        },
        {
            "Name": "Chargeable",
            "Chargeable": "chargeable"
        },
        {
            "Name": "Consumed",
            "Value": "consumed"
        },
        {
            "Name": "Failed",
            "Value": "failed"
        }
    ]
}

Here, Name is a name of the list item, displayed to the Skyvia user. Value is the internal data source API value of the corresponding list item.

StrictEnumValues

Determines whether you can assign only values from the EnumValues list to this field, and custom values are not allowed. The default value is False.

Expression

This setting defines a field value using an expression. You can use it both to define a completely virtual calculated field and to redefine the value of an existing field. When specifying an expression, use the API names of the response object properties. You must specify API names without parentheses or quotes. If the expression uses the name of a nested JSON property, separate the names with the dot (for example, shipping.country).

You can find the Expression syntax and the list of supported functions and operators in our Expression Syntax documentation.

Sortable

This setting indicates whether the endpoint supports native sorting by this field. The default value is false.

If Sortable is set to true, a corresponding SortOperation setting must be defined either at the object level or in the Provider Configuration. If Sortable is enabled but no SortOperation is defined, the configuration is invalid, metadata reading fails with an error.

SortPath

The name or internal path of the GraphQL argument for the value of this field when sorting. The base argument for it is the SortArgument of the SortOperation. It is used when a name different from the one specified in Path must be used. If not specified, Path is used for sorting.

DownloadContent

Use this setting when the value from Path contains a direct download URL to a binary file (a full URL starting with http:// or https://). Valid values are true or false. DownloadContent setting is applicable to binary fields.

When this option is enabled, the connector sends an additional request to the provided URL and returns the binary content from the response. Only one field per object can have DownloadContent enabled.

The connector can automatically assign correct file names and extensions to downloaded files if an object contains this information. To enable this behavior, do the following:

• Name the field with binary content Content.
• Name the field that contains the file name, FileName, or Name.
• If the file extension is provided separately, name the field containing the extension FileExtension or Extension.

This naming convention allows the connector to correctly reconstruct the downloaded file metadata.

FilterOperations

This section contain filter operation configurations, which determine the filtering operations natively supported for the object by the data source API.

For example, below you see the FilterOperations in Fireflies.ai for the CreatedAt field of the Transcripts object. The API supports two arguments for filtering: fromDate and toDate. Using them, we can support filters with GreaterThan, GreaterThanOrEquals, LessThan, and LessThanOrEquals operators.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "Name": "CreatedAt",
  "Path": "dateString",
  "DbType": "DateTime",
  "FilterOperations": [
  {
    "Operation": "GreaterThan",
    "Argument": "fromDate",
    "BasePathPosition": 2,
    "DateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
    "Delta": 1
  },
  {
    "Operation": "GreaterThanOrEquals",
    "Argument": "fromDate",
    "BasePathPosition": 2,
    "DateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
    "Delta": 0
    },
  {
    "Operation": "LessThanOrEquals",
    "Argument": "toDate",
    "BasePathPosition": 2,
    "DateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
    "Delta": 0.999
  },
  {
    "Operation": "LessThan",
    "Argument": "toDate",
    "BasePathPosition": 2,
    "DateTimeFormat": "yyyy-MM-ddTHH:mm:ss.fffZ",
    "Delta": -0.001
  }
]
}

Every FilterOperation setting has the following nested settings:

Operation

Defines the type of filter operation supported by source API. Valid values are Equals, LessThan, LessThanOrEquals, GreaterThan, GreaterThanOrEquals, In.

When the data source API supports the IN operator and IN is declared in the FilterOperations for the field, then the connector behaviour is the following. When you use filters with OR and Equals operators for the same field on the same level, the connector will transform such filter into a one withIN operator and execute it natively. For example, if a query specifies a filter like WHERE (InvoiceId = '111' OR InvoiceId = '222' OR InvoiceId = '333'), the connector will process it internally as WHERE InvoiceId IN ('111', '222', '333') and executed natively.

Argument

The name or internal path of the GraphQL argument for the filter value. Required parameter.

Path

The path to the field where the argument itself should be placed. When BasePathPosition = 0, this is an absolute path.

BasePathPosition

The index of the base path element to which Path (if specified) or Argument (if Path is not specified) is added. Default value is 0. Either Path or BasePathPosition must be specified.

Required

Defines whether the filter is required or not. Can accept the true or false value. Default value is false.

If the filter is required, you can't execute the web request to this object without a filter by this field.

DbType

Redefines the filter argument data type. If omitted, the argument data type is inherited from the field DbType.

SubType

Redefines the filter argument subtype. If omitted, argument subtype is inherited from the field SubType.

TimeStampStoreMode

Redefines the filter argument TimeStampStoreMode. If omitted, argument TimeStampStoreMode is inherited from the field TimeStampStoreMode.

DateTimeFormat

Redefines the filter argument DateTimeFormat. If you omit it, the argument DateTimeFormat is inherited from the field DateTimeFormat.

DateFormat

Redefines the filter argument DateFormat. If you omit it, the argument DateFormat is inherited from the field DateFormat.

TimeFormat

Redefines the filter argument TimeFormat. If you omit it, the argument TimeFormat is inherited from the field TimeFormat.

NullAs

Redefines the filter argument NullAs. If you omit it, the argument NullAs is inherited from the field NullAs.

Delta

This setting specifies an offset that is added to the filter value for numeric and date fields when the request is formed. It is used to adjust filter values so that both inclusive (LessThanOrEquals/GreaterThanOrEquals) and exclusive (LessThan/GreaterThan) comparison operators work correctly.

For numeric fields, only the integer part of the value is used. For date and time values, the offset is applied in seconds.

Many APIs support filtering with a single comparison parameter (for example, by datetime) but interpret it differently: some treat the value as inclusive, others as exclusive. Because of this, an API may natively support only LessThan/GreaterThan or LessThanOrEquals/GreaterThanOrEquals operators, but not both. Delta makes this possible by shifting the filter value. For example, adding one second enables an exclusive GreaterThan filter on top of a native inclusive comparison, while subtracting one second enables an inclusive GreaterThanOrEquals filter on top of a native exclusive comparison.

CacheValue

Specifies whether the value used in a filter should be included in the query result. Allowed values are true or false.

When this setting is enabled, the value of the field used in the filter is added to the resulting object during query execution. This setting is useful when an object supports range filters (for example, from and to), but the API response does not return these values. Enabling CacheValue ensures that the filtered values are available in the result set.

ParentRelations

This section contains parent relationship configurations that define the parent relationships of the current object with another object.

Parent relationship configurations have the following settings:

Field

The foreign key field that refers to the parent object.

RelatedTable

The name of the parent object.

RelatedField

Key field in the parent object by which the foreign key relation is built.

RetrieveSingleOperation

This section defines the operation of fetching a record by its primary key.

We highly recommend specifying this setting if the source API allows getting the object records by their IDs.

For example, the connector performs the request SELECT * FROM Object WHERE Id = <id_value> via 1 API call, with the RetrieveSingleOperation defined. If you omit RetrieveSingleOperation, the connector will read all the object records into the cache and then perform the request to this cache instead of calling the object directly. It takes more time and more API calls.

RetrieveSingleOperation includes the following settings:

Path

The base path of the record in the GraphQL query. The object’s fields in the GraphQL query are appended to the last segment of this path. If Path is not specified, the object’s Path is used instead.

CacheKeys

Takes the ID value from the filter and adds it to the resulting object. Use it when the resulting object returned by RetrieveSingleOperation does not include the key field value, even though the specific record is retrieved by that value. Accepts true or false (default) values.

Arguments

This section contains argument configurations which define the arguments of RetrieveSingleOperation.

Argument configurations contain the following settings:

ColumnName

Name of the key field for RetrieveSingleOperation. Required parameter.

Argument

Name or internal path of the GraphQL operation argument. Required parameter.

Path

Path to the field where the argument is located. When BasePathPosition = 0, this is an absolute path.

BasePathPosition

Index of the base path element (Path from RetrieveSingleOperation) to which Path (if specified) or Argument (if Path is not specified) is added. Default value is 0. Either Path or BasePathPosition must be specified.

CRUD Operations

Settings for INSERT, UPDATE, and DELETE operations for the connector's objects are defined in the InsertOperation, UpdateOperation and DeleteOperation sections. If any of these sections is not specified in an object configuration, the corresponding DML operation is not available for the object.

Every CRUD operation section contains the following settings:

Path

GraphQL path of the mutation for its arguments. GraphQL arguments, which typically contain the fields corresponding to the record on which the DML operation is performed, are appended to the last segment of this path. Required parameter.

ReturningPath

GraphQL mutation path for retrieving mutation results. GraphQL fields corresponding to the object fields from RETURNING, if present, are appended to the last segment. This path must point to a JSON object for INSERT and UPDATE operations, or to any value for a DELETE operation (for example, deletedArticleId). The record or value obtained by this path may participate in:

1. Emptiness check in RowErrorHandling when ErrorThrowPolicy is set to OnEmptyData.
2. Returning, if it is supported and present in the query.
   By default, it is equal to Path.

Headers

Additional web request headers that are sent for this operation. Specify Headers as a JSON array of objects with the Key and Value properties. They are merged with Headers specified in the ProviderConfiguration section as well as with headers in the corresponding setting of an object.

ConstantParameters

Allows to set constant parameters for the specific operation.

These parameters are merged with ConstantParameters specified in the ProviderConfiguration section as well as with ConstantParameters specified on the object level.

ReturningStrategy

JSON object defining how fields are returned when the RETURNING operation is specified. See Provider Configuration ReturningStrategy.

BulkSize

BulkSize is used to insert, update, or delete multiple rows within a single request. So that operations on multiple records are executed faster. Use BulkSize carefully considering that source API may set limits for a single request data volume.

• When set to > 1, the GraphQL mutation contains the number of modified records equal to the value of this parameter. This significantly speeds up DML operations on multiple records.
• When set to ≤ 1 (0 or 1), DML operations are executed row by row Default is 0.

ErrorHandling

Use it to override the object’s ErrorHandling and the provider’s ErrorHandling . ErrorHandling is used to process errors not declared in the query (no additional fields are added to the query for them). For bulk requests, this typically applies when the entire request fails rather than an error occurring in a specific row.

RowErrorHandling

Defines the error handling behavior on record level (a specific GraphQL mutation within the request). This parameter is used when additional fields must be specified in the GraphQL mutation to capture mutation errors. Settings are similar to Provider Configuration ErrorHandling. ErrorsPath and ErrorMessagePath from RowErrorHandling are added to the query. You can use semicolon in the ErrorMessagePath, to add multiple fields to the GraphQL query. For example, "message;path".