getLabelsLinkedToRecordIds

The "getLabelsLinkedToRecordIds" action returns label objects for the specified records in a table. You use the "ids" property to specify the records and the "databaseName", "ownerName", and "tableName" to specify the table.

 

Request examples

Minimal

This example returns the labels linked to records 1 and 2 in the table "my_table" owned by the default account and database 

{
  "action":    "getLabelsLinkedToRecordIds",
  "params":    
  {
    "tableName": "my_table",
    "ids": [1,2]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal 

This example returns the labels linked to records 1 and 2 in the table "my_table" owned by the "db" user in the "faircom" database .

{
  "api":       "db",
  "action":    "getLabelsLinkedToRecordIds",
  "params":    
  {
    "databaseName": "faircom",
    "ownerName": "db",
    "tableName": "my_table",
    "ids": [1,2],

    "verifyLinks": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Minimal

This example returns the record IDs from the specified table that have the specified label.

{
  "result": {
    "databaseName": "faircom",
    "ownerName": "db",
    "tableName": "my_table",
       
    "labels": 
    [
       {
         "group": "myGroup",
         "name": "myLabel1",
         "ids": [1,2]
       },
       {
         "group": "myGroup",
         "name": "myLabel2",
         "ids": [1,2]
       }
    ]
    
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Request properties ("params")

Property Description Default Type Limits (inclusive)

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. 

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

tableName

The "tableName" property contains the unique, user-defined name of a table.

See table name in System specifications for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

ids

An “id” is a unique identifier automatically generated by the server. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create an object such as a label or thing and stores it in the table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property. You can use the "id" or "thingName" properties to identify and look up a thing.

 

 Automatically generated by the server array of integers Each array item is an integer from 0 to 2147483647

The "verifyLinks" property causes the action to verify that the specified labels, records, and tables exist when set to true. If your application has already validated that the labels, records, and tables exist, it can set "verifyLinks" to false, which provides a performance boost because the action does not need to look up this information.

 Optional with default of true Boolean

true

false

 

Response properties ("result")

Property Description Default Type

databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • 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", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

tableName

The "tableName" property is a string containing the name of a table.

See table name in System specifications for the table naming requirements and limitations.

 string 1 to 64 bytes

labels

The "labels" property can assign 1 or more labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 
 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

labels

.group

The "group" property groups labels into a lookup list or tag set. It is an optional namespace for a set of labels that identifies their purpose. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. A group assigned to the empty string "" is the default group.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

When you assign a group name to a label, the server automatically checks whether the group name exists in the list of groups returned by the "listLabelGroups" action. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip: If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name.

 string 1 to 64 bytes

labels

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. 

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 

 string 1 to 64 bytes

labels

.ids

The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. 

  • 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.
 array 0 or more ids

Was this article helpful?

Give feedback about this article

Related Articles