<commit_before># Queries

## Introduction

Data structures in the Chain Core API are represented as key-value JSON objects. This includes local objects, such as accounts and keys, and global objects, such as transactions and assets. To retrieve data, you perform a query with optional parameters. By default, each query returns a time-ordered list of objects beginning with the most recent.

### Filters

Filters allow narrowing results to those matching a set of supplied parameters.

A filter is composed of one or more **terms**, with multiple terms joined with `AND` and `OR`. Each term contains a **property**, **operator**, and **value**. Each term targets a specific field in the key-value (JSON) object (see [API Objects](../reference/api-objects.md)). Terms can be grouped together in a **scope** to target a specific array of sub-objects within an object.

For example, to list transactions where a specific account spends a specific asset, you would create a filter with two terms, scoped to the inputs:

```
inputs(account_alias='alice' AND asset_alias='gold')
```

#### Properties

Any field in a JSON object can be used as a filter property. To use a field that is nested within another field, provide the path to it, starting with the outermost parent object. For example:

```
asset_definition.issuer.name
```

#### Operators

Filters currently support only the `=` operator.

#### Scope

The transaction object contains an array of other objects: an `inputs` array and an `outputs` array. The `inputs()` and `outputs()` filter scopes allow targeting a specific object within those arrays.

For example, the following will return transactions where Alice sent gold to Bob:

```
inputs(account_alias='alice' AND asset_alias='gold') AND outputs(account_alias='bob' AND asset_alias='gold')
```

### Additional parameters

Transaction queries accept time parameters to limit the results within a time window.

| Method             | Description                                                    |
|--------------------|----------------------------------------------------------------|
| setStartTime       | Sets the earliest transaction timestamp to include in results. |
| setEndTime         | Sets the latest transaction timestamp to include in results.   |

Balance and unspent output queries accept a timestamp parameter to report ownership at a specific moment in time.

| Method             | Description                                                                |
|--------------------|----------------------------------------------------------------------------|<commit_msg>docs: clarify filter usage<commit_after># Queries

## Introduction

Data structures in the Chain Core API are represented as key-value JSON objects. This includes local objects, such as accounts and keys, and global objects, such as transactions and assets. To retrieve data, you perform a query with optional parameters. By default, each query returns a time-ordered list of objects beginning with the most recent.

### Filters

Filters allow narrowing results to those matching a set of supplied parameters.

A filter is composed of one or more **terms**, with multiple terms joined with `AND` and `OR`. Each term contains a **property**, **operator**, and **value**. Each term targets a specific field in the key-value (JSON) object (see [API Objects](../reference/api-objects.md)). Terms can be grouped together in a **scope** to target a specific array of sub-objects within an object.

For example, to list transactions where a specific account spends a specific asset, you would create a filter with two terms, scoped to the inputs:

```
inputs(account_alias='alice' AND asset_alias='gold')
```

#### Properties

Any field in a JSON object can be used as a filter property. To use a field that is nested within another field, provide the path to it, starting with the outermost parent object. For example:

```
asset_definition.issuer.name
```

Note: although you can create asset definitions, tags, and reference data with any valid JSON object, you can only query fieldnames that contain **letters**, **numbers**, and **underscores**.

#### Operators

Filters currently support only the `=` operator, which allows you to search for exact matches of **string** and **integer** values. Other data types, such as booleans, are not supported.

There are two methods of providing search values to the `=` operator. First, you can include them inline, surrounded by single quotes:

```
alias='alice'
```

Alternatively, you can specify a parameterized filter, without single quotes:

```
alias=$1 OR alias=$2
```

When using parameterized filters, you should also provide an ordered set of values for the parameters:

```
["Bob's account", "Bob's dog's account"]
```

The SDK supports both parameterized and non-parameterized filters. The dashboard does **not** support parameterized filters.

#### Scope

The transaction object contains an array of other objects: an `inputs` array and an `outputs` array. The `inputs()` and `outputs()` filter scopes allow targeting a specific object within those arrays.

For example, the following will return transactions where Alice sent gold to Bob:

```
inputs(account_alias='alice' AND asset_alias='gold') AND outputs(account_alias='bob' AND asset_alias='gold')
```

### Additional parameters

Transaction queries accept time parameters to limit the results within a time window.

| Method             | Description                                                    |
|--------------------|----------------------------------------------------------------|
| setStartTime       | Sets the earliest transaction timestamp to include in results. |
| setEndTime         | Sets the latest transaction timestamp to include in results.   |

Balance and unspent output queries accept a timestamp parameter to report ownership at a specific moment in time.

| Method             | Description                                                                |
|--------------------|----------------------------------------------------------------------------|
{'fraction_non_alphanumeric': 0.13193304890055793, 'fraction_numerical': 0.0003281916639317361, 'mean_word_length': 2.8454258675078865, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 9, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3616132', 'n_tokens_mistral': 1349, 'n_tokens_neox': 1292, 'n_words': 741}