Read records from a table

Read existing records in a table using the API.

See also: Example: Copy updated records

URL

Use a URL in the following form to invoke the API:

POST https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action

Where:

  • {appId} specifies the GUID of the AppSheet application. You can obtain the {appId} from the Manage > Integrations > IN pane.
  • {tableName} specifies the name of the table.

Request body

The HTTP request body contains:

  • The Action name Find.
  • Optional properties such as Locale, Location, and Timezone.
    The Locale is used when validating Date, Time, DateTime, Decimal, Percent, and Price data values. For example, when Locale is en-US, date values must be entered in MM/DD/YYYY format. When Locale is en-GB, date values must be entered in DD/MM/YYYY format.
  • The optional Selector property.

Examples

Read all rows

You can omit the Selector property and not specify any input Rows. This will return all rows in the table.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
]
}

Read selected rows

In the Selector property, you can specify a SELECT() expression that yields a list of record key values. The records identified by the key values are returned in the Rows response.

The Select expression can refer to a slice.

You can specify an ORDERBY() expression to control the sort order of the returned records. 

You can specify a TOP() expression to limit the number of returned rows.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Selector": "Filter(People, true)",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
]
}


The Selector can take many forms including:

"Selector": "Filter(People, true)"
"Selector": "Filter(People, [Age] >= 21)"
"Selector": "Select(People[_ComputedKey], And([Age] >= 21, [State] = "CA"), true)"
"Selector": "OrderBy(Filter(People, [Age] >= 21), [LastName], true)"
"Selector": "Top(OrderBy(Filter(People, [Age] >= 21), [LastName], true), 10)"
"Selector": "Top(OrderBy(Select(People[_ComputedKey], And([Age] >= 21, [Date Hired] > "01/01/2016"), true), [LastName], false), 100)"

Read input rows

You can omit the Selector property and specify input Rows containing the key values of the records to be read. This will return all rows having matching key values from the table.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
{
"FirstName": "Jan",
"LastName": "Jones",
}
]
}

Security filters

The Find is performed under the identity of the application owner by default. Your can override this by specifying the RunAsUserEmail property in the request properties.

Security filters are applied when the Find is performed.

Response body

The API returns the rows in HTTP contents.

The returned records include all field values. This includes virtual fields and field values computed by worksheet formulas.

{
  "Rows": [
{
"_RowNumber": 10,
"FirstName": "Jan",
"LastName": "Jones",
"Age": 33,
"Department": "Accounting",
"Street": "110 Beach Blvd",
"City": "Newport Beach",
"State": "CA",
"Zip": 92661,
"Home Phone": 4257868765,
"Fax": 4253214432,
"Date Hired": "10/31/2014",
"Arrived": "8:15:25",
"Departed": "18:30:33",
"Last Review": "08/31/2017 23:59:59",
"Rating": 0.9950,
"Salary": 3333.45,
"Image": "http://images6.fanpop.com/image/photos/36300000/Emilia-Clarke-image-emilia-clarke-36399128-460-276.jpg"
}
]
}

Response HTTP status codes

See Response HTTP status codes in Invoke an action.

What happens when a record is read?

  1. The record is retrieved based on the key values you specify.
  2. The record is returned in the HTTP content.

Error: Row having key not found

See Troubleshoot API calls for information on the following error:

Row having key '<key value>' not found

Was this helpful?
How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
Search Help Center
false