> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# Filtering

Most list endpoints in NeMo Platform accept a `filter` parameter for narrowing results. Filter values can be expressed as dot flags (CLI only), bracket notation (URLs), text syntax (compact, URL-aware callers), or JSON (SDKs and programmatic builders).

Prefer the form that's most natural for the caller:

* **CLI**: `--filter.<field>` dot flags for simple cases → `--filter '<text>'` when you need operators/boolean logic → `--filter '<json>'` for complex nested queries.
* **REST URL**: `?filter[field][$op]=value` bracket notation → JSON blob (`?filter={...}` URL-encoded) → text syntax (readable but requires URL-encoding spaces and quotes).
* **SDK**: JSON dicts on typed endpoints; text or JSON strings on endpoints whose `filter` parameter is typed as `str` (`client.projects.list`, `client.workspaces.list`, `client.entities.list`).

## Filter syntaxes

### CLI dot flags

Generated CLI list commands expose each simple filter field as its own option:

```bash
nemo files filesets list --filter.purpose dataset --filter.storage-type local
```

Dot flags cover exact-match on scalar fields. For operators (`$gte`, `$like`, …) or boolean combinations, fall through to `--filter` with text or JSON:

```bash
nemo files filesets list --filter 'purpose:"dataset" AND created_at>="2025-01-01"'
nemo files filesets list --filter '{"created_at":{"$gte":"2025-01-01"}}'
```

### Bracket notation

The preferred form for REST query strings. Each `?filter[field][$op]=value` pair is URL-encoding-friendly and composable:

```
GET /apis/files/v2/workspaces/{workspace}/filesets?filter[purpose]=dataset&filter[created_at][$gte]=2025-01-01
```

When no operator is specified, the default is `$eq`:

```
?filter[purpose]=dataset # equivalent to filter[purpose][$eq]=dataset
```

On datetime fields, bare bracket values also default to `$eq` — `?filter[created_at]=2025-01-01` matches only rows whose timestamp equals `2025-01-01` exactly, which is rarely what you want. Use an explicit comparison operator (`$gte`, `$lte`, `$gt`, `$lt`) for datetime fields.

### Text syntax

A compact, human-readable query string. Handy for CLI and SDK string filters; in URLs you need to URL-encode spaces and quotes, so bracket notation is usually easier there.

```bash
nemo files filesets list --filter 'purpose:"dataset" AND created_at>"2025-01-01"'
```

```python
projects = client.projects.list(filter='name~"eval" AND created_at>"2025-01-01"')
```

**Text operators:**

| Operator | Meaning                            | Example                           |
| -------- | ---------------------------------- | --------------------------------- |
| `:`      | Exact match (case-sensitive)       | `name:"mmlu"`                     |
| `~`      | Substring match (case-insensitive) | `name~"llam"`                     |
| `>`      | Greater than                       | `created_at>"2025-01-01"`         |
| `>=`     | Greater than or equal              | `created_at>="2025-01-01"`        |
| `<`      | Less than                          | `updated_at<"2025-12-31"`         |
| `<=`     | Less than or equal                 | `updated_at<="2025-12-31"`        |
| `IN`     | Value in list                      | `status IN ["active", "pending"]` |
| `NOT IN` | Value not in list                  | `status NOT IN ["deleted"]`       |
| `-`      | Negation (prefix)                  | `-status:"draft"`                 |

Combine conditions with `AND`, `OR`, and parentheses:

```
name~"llama" AND (status:"active" OR status:"pending")
```

Spaces between conditions are treated as implicit `AND`.

String values must be double-quoted.

### JSON

Pass a dictionary to the `filter` parameter. Keys are field names; values are either a literal (for exact match) or an operator object. This form is most useful when building queries programmatically:

```python
# Exact match
results = client.files.filesets.list(filter={"purpose": "dataset"})

# Operator syntax
results = client.files.filesets.list(filter={"name": {"$like": "training"}})

# Multiple conditions
results = client.files.filesets.list(
    filter={
        "$and": [{"purpose": "dataset"}, {"description": {"$like": "training"}}]
    }
)

# Date range
results = client.files.filesets.list(
    filter={
        "created_at": {"$gte": "2025-01-01T00:00:00", "$lte": "2025-06-30T23:59:59"}
    }
)
```

When a bare value is provided (without an operator object), it defaults to `$eq`:

```python
# These are equivalent
client.files.filesets.list(filter={"purpose": "dataset"})
client.files.filesets.list(filter={"purpose": {"$eq": "dataset"}})
```

## Operators reference

| Operator | Meaning                            | Example (JSON)                                    |
| -------- | ---------------------------------- | ------------------------------------------------- |
| `$eq`    | Exact match (case-sensitive)       | `{"name": {"$eq": "mmlu"}}`                       |
| `$like`  | Substring match (case-insensitive) | `{"name": {"$like": "mmlu"}}`                     |
| `$lt`    | Less than                          | `{"created_at": {"$lt": "2025-06-01"}}`           |
| `$lte`   | Less than or equal                 | `{"created_at": {"$lte": "2025-06-01"}}`          |
| `$gt`    | Greater than                       | `{"created_at": {"$gt": "2025-01-01"}}`           |
| `$gte`   | Greater than or equal              | `{"created_at": {"$gte": "2025-01-01"}}`          |
| `$in`    | Value in set                       | `{"status": {"$in": ["active", "pending"]}}`      |
| `$nin`   | Value not in set                   | `{"status": {"$nin": ["deleted"]}}`               |
| `$and`   | Logical AND                        | `{"$and": [{"name": "a"}, {"status": "active"}]}` |
| `$or`    | Logical OR                         | `{"$or": [{"name": "a"}, {"name": "b"}]}`         |
| `$not`   | Logical NOT                        | `{"$not": {"status": "draft"}}`                   |

## Nested fields

The API supports filtering on labels via `extra_query` with bracket notation:

```python
# Filter by a custom label
benchmarks = client.evaluation.benchmarks.list(
    extra_query={"filter[labels.eval_category]": "agentic"}
)
```

The equivalent REST call:

```
?filter[labels.eval_category]=agentic
```

## Common patterns

### Date range

```python
results = client.evaluation.metrics.list(
    filter={
        "created_at": {"$gte": "2025-01-01T00:00:00", "$lte": "2025-06-30T23:59:59"}
    }
)
```

### Substring match

```python
models = client.models.list(filter={"name": {"$like": "llama"}})
```

### Multiple conditions

```python
metrics = client.evaluation.metrics.list(
    filter={"$and": [{"name": {"$like": "bleu"}}, {"type": "llm-as-a-judge"}]}
)
```

### Filtering by status

```python
jobs = client.jobs.list(
    workspace="default",
    filter={"source": "customization", "status": "completed"},
)
```