s = CS.Data.queryCases(dataId := ...,
ʃ, 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 |
| 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 cases to return from the query. | number
not required |
| offset | The number of cases 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 action returns an array of cases.
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 all cases, included deleted cases, in a loop
// using a limit of 50 cases to reduce the number of
// cases returned by each query
const limit = 50;
for (let offset = 0; ; offset += limit) {
const cases = CS.Data.queryCases({
dataId: dataId,
status: "all",
limit: limit,
offset: offset
});
// print the key and UUID of each case
cases.forEach(caseData => {
print(`${caseData.key} (${caseData.uuid})`);
});
// if fewer cases are returned than the limit,
// then there are no additional cases
if (cases.length < limit) {
break;
}
}