"getRecordsByIds"

• A zero-length "databaseName" is invalid.

• Its limits are from 0 to 64 bytes.

• If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.

• If no default database is specified during "createSession", "defaultDatabaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.

• The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.

• It is typically an array of integers ("ids": [1,3,5]).

• It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).

  • A string "id" supports numbers larger than 9,007,199,254,740,991.

  • This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.

• It can be the primary key value of another field in the table making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.

  If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).

• If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.

  Tip

  The "getRecordsByIds'' action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

• The "ownerName" property is optional and has a dynamic default value.

• If the "ownerName" property is omitted or set to null, the server uses the value of the "defaultOwnerName" property supplied during the "createSession" action.

• If the "defaultOwnerName" property is not defined, the server uses the "admin" as the owner name.

• The owner of an object has administrative rights over that object.

• The "ownerName" property is a namespace for an object. You can think of it as a container of objects.

  The "ownerName" allows users to use any name for the objects they create — for example, a QA engineer may copy tables into their owner space to run a set of tests.

  It is common for a user to create their own copies of objects from other accounts for testing, troubleshooting, and fixing data. The copied objects can retain the same name because the "ownerName" distinguishes between them.

• The fully qualified name of an object is the "databaseName", "ownerName", and the object's name, such as "tableName" meaning a FairCom server may contain many tables with the name "mytable" as long as each one is in a different database or in a different owner space.

  For example, an organization often creates different databases for different phases of the development lifecycle, such as dev, test, stage, ua, and prod. Each of these databases contains the same set of objects with the same names. Applications leave the "databaseName" out of their JSON actions and use the "defaultDatabaseName" property to specify the target database.

• Queries and scripts are often written without specifying "databaseName" and/or "ownerName", allowing queries and scripts to work properly when run in different databases or in different schemas.

• "primaryKeys" is best used if tables were created with primary keys composed of multiple fields. If primary keys are composed of a single field, it is best to use "ids".

  Note

  Tables created using JSON DB API actions cannot create primary keys composed of multiple fields.

• A table must have a primary key defined in order to use "primaryKeys"

• The "primaryKeys" property is mutually exclusive with the "ids" property meaning it is required when "ids" is omitted or an error is returned if both have values.

• The  "primaryKeys" property is an array of arrays

  • The outer array contains one or more primary key definitions which allow the server to retrieve multiple records at a time.

  • Each inner array is a primary key definition that specifies the values the server needs to retrieve one matching record.

  • A primary key definition consists of one or more objects where each object is a field-value pair that uses the following structure ({ "fieldName": "someField","value": "someValue" }).

• You can use a topic name for an MQTT table because FairCom automatically generates a table name for each topic.

• A "tableName" cannot begin with a number.

• It refers to the name of the integration table that stores a topic’s messages and is used to rename that table or assign a new topic to an existing integration table.

• MQTT automatically creates an integration table for each new topic it receives. Thus, when a message is sent to a topic, FairCom Edge automatically creates a table to hold it.

• As you refine your integration processes, you may want to rename an integration table to better label the data it holds. You can use the "tableName" property of the "configureTopic" action to rename an integration table.

• The "alterIntegrationTable" action can also be used to rename an integration table, but it is less convenient because you must know the original name of the integration table.

• The "binaryFormat" property may occur inside "params",  "responseOptions", "defaultResponseOptions" , and "result".

• When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.

  For example, when  "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.

• When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.

  For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.

• When "binaryFormat" occurs in "result" it signifies how binary values are represented.

  For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.

• The following are the possible values for each format.

  • "base64"

    When the server reads and writes from a binary field, it represents the binary value as a base64 string.

    • This is the default

    • "base64" strings contain the following characters:

      • 0-9

      • A-Z

      • a-z

      • +

      • /

      • =

  • "hex"

    When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.

    • Hexadecimal is easier for people to read and convert to binary.

    • Hexadecimal creates a larger payload than "base64", which makes it less efficient for data transmission.

    • Hexadecimal strings contain the following characters:

      • 0-9

      • A-F

  • "byteArray"

    When the server reads and writes from a binary field, it represents the binary value as an array of bytes.

    • An array of bytes is easiest for a program to manipulate.

    • An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.

    • An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:

      • "aBinaryField": [ 255, 0, 255 ]

Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.

• "dataFormat" in the request inside "responseOptions" determines how the "data" property in the response is formatted.

  Possible values include:

  • "arrays"

    This is the default and causes the server to return results as an array of arrays, which is the most efficient.

  • "objects"

    This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

• "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.

  Possible values include:

  • "arrays"

    This causes the server to return results as an array of arrays, which is the most efficient.

  • "objects"

    This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

  • "autoDetect"

    This is the default and causes the server to automatically detect the format of the data in the "sourceData" property.

• "dataFormat" in the response shows the client how the server formatted the "data" property.

  Possible values include:

  • "arrays"

    This is the default and causes the server to return results as an array of arrays, which is the most efficient.

  • "objects"

    This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

• It makes it easy to know how many records were requested in the last call to "getRecordsFromCursor".

• An application can use "requestedRecordCount" in conjunction with "returnedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.

• It makes it easy to know how many records were returned from the last call to "getRecordsFromCursor".

• An application can use "returnedRecordCount" in conjunction with "requestedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.

• The "totalRecordCount" is set to -1, when the server does not know the total record count.

• A very fast way to get the total number of records in a table is to call the "getRecordsByTable" method without applying a "tableFilter". This immediately returns the count without reading and counting records.

• For most methods, the server does not calculate "totalRecordCount" because calculating it requires walking all records in the query, which may take a significant amount of time.

• When the result is returned as a cursor, "totalRecordCount" is the total number of records that the cursor can traverse.

  Note

  This does not apply to cursor responses.

• When the result returns records directly, "totalRecordCount" is the total number of records that can be retrieved – not necessarily the number of records returned.