s = CS.Data.query(dataId := ...,
content := ...ʅ
ʃ, status := ...ʅ
ʃ, sort := ...ʅ
ʃ, filter := ...ʅ
ʃ, limit := ...ʅ
ʃ, offset := ...ʅ
ʃ, serializationOptions := ...ʅ) | Argument | Description | Types / Required |
|---|
| dataId | The resource ID returned by Data.open, or a dictionary name. | number, string
recommended |
| content | The content to query. | string
required |
| status | Options for the status of the cases to query.
The default value is "notDeletedOnly". | string
not required |
| sort | Options for how the queried data should be sorted. | object
not required |
| filter | Options for how the queried data should be filtered. | object
not required |
| limit | The maximum number of results to return from the query. | number
not required |
| offset | The number of results to skip before starting to return results from the query.
The default value is 0. | number
not required |
| serializationOptions | Options for how cases should be serialized. | object
not required |
The data source is identified using
dataId. If specified as a string, it references the data source that is connected to a dictionary that is part of an application. If specified as a number, it is processed as a
resource ID returned by
Data.open. This typically references non-application data sources. While optional, this should generally be specified explicitly. (If there is only one data source open, the resource ID can be calculated implicitly.)
The string argument status can be used to filter cases by "status":
- "all": Do not apply a filter, processing all cases, including deleted cases.
- "notDeletedOnly": Process only non-deleted cases.
- "partialsOnly": Process only non-deleted cases that are partially saved.
- "duplicatesOnly": Process only non-deleted cases where there are at least two cases with the same key.
The argument sort, an object, can be used to modify the order of the query's results. The filters include two primary values: order and ascending:
| Order | Ascending | Description |
|---|
| "key" | true | Results are ordered by key in ascending order. |
| "key" | false | Results are ordered by key in descending order. |
| "position" | true | Results are ordered by "position" in ascending order. |
| "position" | false | Results are ordered by "position" in descending order. |
In other contexts, CSPro refers to key order as "indexed" and position order as "sequential." If not specified, results are ordered in ascending order.
The argument filter, an object, can be used to further filter cases. The filters include two primary values: operator and value:
| Operator | Description |
|---|
| "startswith" | Only consider cases with a key starting with the specified value. |
| "<" | Only consider cases with a key that is less than the specified value. |
| "<=" | Only consider cases with a key that is less than or equal to the specified value. |
| ">=" | Only consider cases with a key that is greater than or equal to the specified value. |
| ">" | Only consider cases with a key that is greater than the specified value. |
Alternatively, by defining
type as
"position", these checks (other than
"startswith") will apply to the "
position" of a case. The type is
"key" by default.
By default, the action returns all results in the data source that match the query. This may be more information than necessary. When working with a large amount of data, you will want to query only a subset of the data using the
limit and
offset arguments. The limit sets the maximum number of results that the query should return. The offset specifies a certain number of results to skip before starting to return results. Together, these values can be used to incrementally process results. For example, a limit of 20 with an offset of 50 would return results ordered 51–70. The
Data.queryCases documentation includes an
example of using a limit to process cases in a loop.
The action returns an array of keys, summaries, or cases, or a number with a count.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The data source ID is not valid.
- There is an error interacting with the data source.
const dataId = /* retrieved from a call to CS.Data.open */;
// query the summaries to get information about the
// last case in the data source (sorted by key)
const summaryQuery = CS.Data.query({
dataId: dataId,
content: "summaries",
status: "all",
sort: {
order: "key",
ascending: false
},
limit: 1
});
if (summaryQuery.length !== 0) {
const lastCaseSummary = summaryQuery[0];
print(`Sorted by key, the last key is "${lastCaseSummary.key}" ` +
`(located at position: ${lastCaseSummary.position}).`);
}