Searching legacy object records

Note: There is a new custom objects experience. See the Custom Object APIs.

You can search the legacy custom object records in your account by one or more property values, refine the search by legacy object type, and filter the results by date range.

See Legacy Custom Objects Search for the API reference.

About the search requests

Use the following request to search object records:

POST /api/sunshine/objects/query

Specify the search conditions in a JSON object included in the body of the request. Example:

{
  "query": {
    "color": {"$contains": "magenta"}
  },
  "created": {
    "start": "2020-01-01 14:54:17.019",
    "end": "2020-03-05 09:23:08.063"
  }
}

The query object is required for all searches. It defines your search conditions. You can search by property value and refine the search by legacy object type. For more information, see the following topics in this article:

• Searching by property value
• Refining the search by legacy object type

You can also include a _created_at or _updated_at object to filter the results by date range. See Filtering the results by date range.

Example

Data

• Request body saved to search.json file:

  {
    "query": {
      "$and": [
        {"author": {"$contains": "Sheldon"}},
        {"_type": {"$eq": "book"}}
      ]
    },
    "_created_at": {
      "start": "2019-07-01 00:00:00.000",
      "end": "2019-12-31 23:59:59.999"
    },
    "sort_by": {
      "_created_at": "desc"
    }
  }

  The rest of this article explains what this data means. It basically asks to search for records of type "book" that have an author property that contains the string "Sheldon". It limits the results to only records created between July 1, 2019, and Dec 31, 2019, and lists them in descending order.

curl request

curl https://coolreads.zendesk.com/api/sunshine/objects/query \
  -d @search.json \
  -H "Content-Type: application/json" \
  -v -u [e-mail]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

Python request

import json

import requests


with open('search.json', mode='r') as f:
    search = json.load(f)

url = 'https://coolreads.zendesk.com/api/sunshine/objects/query'
api_token = '6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv'
headers = {'Content-Type': 'application/json'}
credentials = '[email protected]/token', api_token
response = requests.post(url, json=search, auth=credentials, headers=headers)
if response.status_code != 200:
    print(f'{response.status_code}: {response.text}')
else:
    print(response.json())

About the search responses

The response to any search for legacy object records consists of a JSON object with two properties:

• an array named data that lists the legacy object records that match the search conditions. See Legacy Object Records for the format of the records
• a links object containing a next URL to paginate through the results. Search uses cursor-based pagination so the URL contains a token

Example

Status: 200 OK

{
  "data": [
    {
      "type": "book",
      "id": "5d13764c-cf5f-11e9-aa86-2f9bb45ad15c",
      "external_id": null,
      "created_at": "2019-09-04T22:00:10.191Z",
      "updated_at": "2019-09-04T22:00:10.191Z",
      "attributes": {
        "book_price": 542,
        "book_available": true,
        "author": "Sidney Sheldon",
        "name": "The Doomsday Conspiracy",
        "publisher": "Bloomsbury publications"
      }
    },
    {
      "type": "book",
      "id": "70588682-ca8d-11e9-893a-63225c9f1206",
      "external_id": null,
      "created_at": "2019-08-29T18:47:23.556Z",
      "updated_at": "2019-08-29T18:47:23.556Z",
      "attributes": {
        "book_price": 542,
        "book_available": true,
        "author": "Sidney Sheldon",
        "name": "If Tomorrow Comes",
        "publisher": "Bloomsbury publications"
      }
    }
  ],
  "links": {
    "previous": null,
    "next": "/api/sunshine/objects/query?per_page=50&page=2"
  }
}

By default, the search endpoint returns ten records per page. You can change the number by specifying a per_page parameter in the request URL of up to 1000. Example:

POST /api/sunshine/objects/query?per_page=50

Searching by property value

You can search based on the values of a legacy object's properties. A legacy object's properties are defined in the schema for the legacy object type. See Creating a schema for a legacy custom object.

Building a basic query

A query consists of one or more search conditions. Each search condition specifies a test to apply to a record. If a record meets the condition or conditions, the record is considered a match.

A single search condition consists of a property name and a legacy object containing a comparison operator and value. For example, if the schema for your legacy object type defines a color property, then you can return all records that have a color property equal to "blue" using the following query:

{
  "query": {
    "color": {"$contains": "blue"}
  }
}

In the example, $contains is the comparison operator. The operators you can use depend on the data type of the value.

Data type	Operators
string	$contains, $eq
number	$eq, $neq
array	$contains
object	$not
boolean	$eq, $neq

For more information about the operators, see Comparison Object in the API reference. For example, despite its name, the $contains operator looks for whole word matches. If you search for "sig", the response will not contain any instances of "sign".

Searching by property value returns the records of any legacy object type with a property of the same name. For example, if a car and a boat object type both have a color property, the search returns matching car and boat records. To limit the search to a specific legacy object type, see the next section, Refining the search by legacy object type.

Using a wildcard to search all properties

If you don't know the name of a property or you're unsure, you can use the asterisk (*) wildcard character for the property name to return all the records that meet the condition. Example:

{
  "query": {
    "*": {"$contains": "blue"}
  }
}

The search returns any record that has any property that contains the value "blue".

Specifying more than one condition

You can specify more than one search condition in an array. To specify that the records must match all the conditions, use the $and operator. Example:

{
  "query": {
    "$and": [
      {"color": {"$contains": "blue"}},
      {"model": {"$contains": "CR"}}
    ]
  }
}

To specify that the records must match one of the conditions, use the $or operator. Example:

{
  "query": {
    "$or": [
      {"model": {"$contains": "CW"}},
      {"model_year": {"$eq": 2019}}
    ]
  }
}

You can also nest conditions to refine your search. The following search looks for all products that have "CW" in their model name, are blue, and are either a 2019 or a 2020 model:

{
  "query": {
    "$and": [
      {"model": {"$contains": "CW"}},
      {"color": {"$contains": "blue"}},
      {
        "$or": [
          {"model_year": {"$eq": 2019}},
          {"model_year": {"$eq": 2020}}
        ]
      }
    ]
  }
}

Refining the search by legacy object type

Searching by property value can return records from more than one legacy object type if the types have a property of the same name. You can refine the search by object type with the _type keyword. Example:

{
  "query": {
    "$and": [
      {"_type": {"$eq": "boat"}},
      {"color": {"$contains": "blue"}}
    ]
  }
}

You can also use _type conditions in nested queries.

The comparison operators you can use with type names are $eq and $neq.

Filtering the results by date range

You can specify a date range to filter the results based on the legacy object records' created_at or updated_at timestamps.

For example, the following search returns the legacy object records created in the two-month period between January 1 and February 29, 2020:

{
  "query": {
    "model": {"$contains": "CR300"}
  },
  "_created_at": {
    "start": "2020-01-01 00:00:00.000",
    "end": "2020-02-29 23:59:59.999"
  }
}

You can specify a _created_at or an _updated_at date range.

The datetimes defining the start and end range must be in the format "yyyy-MM-dd HH:mm:ss.SSS".

Sorting the results

You can sort the results by timestamp by including a sort_by parameter:

{
  "query": {
    "model": {"$contains": "CVX300"}
  },
  "sort_by": {
    "_created_at": "asc"
  }
}

You can specify "asc" or "desc" for the sort order.

For more information, see Sorting results.