Skip to main content

Selectively return fields

Most query actions allow you to specify which fields to include or exclude from each record that is returned in the results. To do this, you use either the "includeFields" or the "excludeFields" properties. These two properties are mutually exclusive.

All fields are included in the results when both the "includeFields" and the "excludeFields" properties are omitted, or contain empty arrays, or are null. This is the default.

By default, the "id" and "changeId" fields are always included in the results because "id" is needed to look up records and "changeId" is needed when using optimistic record updates. If you do not want them to be included automatically, also set the "excludeOptionalFields" property to true.

Example 1. Example of an action that include only the name and email field of a person table
{ 
  "requestId": "1",
  "action": "getRecordsByPartialKeyRange",
  "params": 
  {
    "databaseName": "myDatabase",
    "tableOwner": "userNameOfAccountThatOwnsTheTable",
    "tableName": "persons",
    "indexFilter": 
    {
      "indexName": "NameIndex",
      "partialKey": "Mi" 
    },

     "responseOptions": 
     { 
       "dataFormat": "arrays", 

       "includeFields": [ "name", "email" ],
       "excludeFields": [],

       "excludeOptionalFields": true
     }
    "apiVersion": "1.0",
    "authToken": "anAuthorizationTokenFromTheServer"
  }
}


Why return a subset of available fields and properties?

  • Processing fewer fields on the server delivers results faster.

  • Reducing the size of the returned data, speeds network transmission.

  • Making the results match your exact needs, makes your program run faster and easier to program.