> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operators

> Understand how Clinia's operators enable precise search and filtering across the platform

# Operators

Operators are the fundamental building blocks of Clinia's filtering and selection language, enabling you to define conditions that records must satisfy across various platform features.
Whether you are working with resources or relationships, operators provide a unified interface for expressing complex logic when **searching**, **filtering**, or **validating** records throughout your data workflows.

## Understanding Operators

Operators in Clinia work by defining conditions that records must satisfy to be selected for a particular operation. Whether you're searching for specific records, configuring conditional ingestion steps, setting up field validation rules, or filtering data for processing, operators provide the precise control you need. Each operator is designed for specific data types and use cases, from simple equality checks to complex semantic similarity matching.

## Where Operators Are Used

Operators are currently used in two main areas of the Clinia platform:

### Data Partition API

* **Record filtering**: Filter and retrieve specific records from data partitions (resources or relationships)
* **Transactional queries**: Define precise selection criteria for search operations
* **Hybrid Search queries**: Combine different matching strategies (semantic, lexical)

### Registry API

* **Data quality rules**: Define validation criteria that fields must satisfy
* **Conditional processing**: Apply transformations only when records meet specific criteria
* **Pipeline routing**: Determine which processing steps to execute based on record properties

### Operator Categories

Clinia's operators fall into several categories based on their purpose:

| Category                                  | Purpose                                                 | Operators          | Use Cases                                        |
| ----------------------------------------- | ------------------------------------------------------- | ------------------ | ------------------------------------------------ |
| **[Comparison](#comparison-operators)**   | Test numerical, date or code value relationships        | `eq`, `lt`, `gt`   | Status checks, date ranges, numerical thresholds |
| **[Collection](#collection-operators)**   | Work with arrays and multiple values                    | `any`, `all`       | Multi-select filters, requirement validation     |
| **[Text Search](#text-search-operators)** | Handle textual content with various matching strategies | `match`            | Full-text search, content filtering              |
| **[Semantic](#semantic-operators)**       | Enable AI-powered dense vector similarity matching      | `knn`              | Semantic search, hybrid search                   |
| **[Spatial](#spatial-operators)**         | Support location-based filtering                        | `geoDistance`      | Proximity searches, geographic boundaries        |
| **[Logical](#logical-operators)**         | Combine multiple conditions                             | `and`, `or`, `not` | Complex filtering logic, condition composition   |
| **[Composite](#composite-operators)**     | Apply conditions within nested data structures          | `composite`        | Related data queries, nested filtering           |

## Comparison Operators

### Equal (`eq`)

Tests if a property has the same value or some equivalence. Supports case-insensitive matching for symbol types and wildcard matching.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types), [Temporal Types](/explanation/data-types/base-types#temporal-types), [Integer](/explanation/data-types/base-types#numerical-types), [Decimal](/explanation/data-types/base-types#numerical-types), [Boolean](/explanation/data-types/base-types#boolean-boolean), [Geographic Types](/explanation/data-types/base-types#geopoint-geopoint)

```json theme={null}
{
  "eq": {
    "propertyKey": "value"
  }
}
```

**Examples**:

```json theme={null}
// Exact match
{
  "eq": {
    "status": "active"
  }
}

// Wildcard for existence check
{
  "eq": {
    "email": "*"
  }
}

// Partial wildcard match
{
  "eq": {
    "name": "John*"
  }
}
```

<Note>
  The wildcard `*` tag is a powerful tool for matching any value, including empty strings. It can be used to check if a field exists or to match any value that starts with a specific prefix.
</Note>

### Less Than (`lt`)

Tests if a property has a value lower than the specified value. Only works with comparable data types.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types) (`symbol`, `code`, `markdown`), [Temporal Types](/explanation/data-types/base-types#temporal-types) (`date`, `datetime`, `time`, `instant`), [Numeric Types](/explanation/data-types/base-types#numerical-types) (`integer`, `decimal`)

```json theme={null}
{
  "lt": {
    "propertyKey": "value"
  }
}
```

**Examples**:

```json theme={null}
// Date comparison
{
  "lt": {
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

// Numerical comparison
{
  "lt": {
    "age": 65
  }
}
```

### Greater Than (`gt`)

Tests if a property has a value greater than the specified value. Only works with comparable data types.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types) (`symbol`, `code`, `markdown`), [Temporal Types](/explanation/data-types/base-types#temporal-types) (`date`, `datetime`, `time`, `instant`), [Numeric Types](/explanation/data-types/base-types#numerical-types) (`integer`, `decimal`)

```json theme={null}
{
  "gt": {
    "propertyKey": "value"
  }
}
```

**Examples**:

```json theme={null}
// Find recent records
{
  "gt": {
    "lastModified": "2024-08-01T00:00:00Z"
  }
}

// Numerical threshold
{
  "gt": {
    "score": 75.5
  }
}
```

## Collection Operators

### Any (`any`)

Tests if a property contains any of the given values. Uses equality (`eq`) operator for each value.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types), [Temporal Types](/explanation/data-types/base-types#temporal-types), [Integer](/explanation/data-types/base-types#numerical-types), [Decimal](/explanation/data-types/base-types#numerical-types), [Boolean](/explanation/data-types/base-types#boolean-boolean), [Geographic Types](/explanation/data-types/base-types#geopoint-geopoint), [Array Types](/explanation/data-types/base-types#array)

```json theme={null}
{
  "any": {
    "propertyKey": ["value1", "value2", "value3"]
  }
}
```

**Example**:

```json theme={null}
{
  "any": {
    "specialties": ["Cardiology", "Internal Medicine", "Family Medicine"]
  }
}
```

<Warning>
  The `any` operator is inclusive and will return true if any of the specified values are found within the property. This means that if the property is an array, it will check each element for a match. The `any` operator therefore checks for **partial** intersection for array datatypes.
</Warning>

### All (`all`)

Tests if an enumerable property contains all of the given values. Uses equality comparison for each value.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types), [Temporal Types](/explanation/data-types/base-types#temporal-types), [Integer](/explanation/data-types/base-types#numerical-types), [Decimal](/explanation/data-types/base-types#numerical-types), [Boolean](/explanation/data-types/base-types#boolean-boolean), [Geographic Types](/explanation/data-types/base-types#geopoint-geopoint), [Array Types](/explanation/data-types/base-types#array)

```json theme={null}
{
  "all": {
    "propertyKey": ["value1", "value2"]
  }
}
```

**Example**:

```json theme={null}
{
  "all": {
    "requiredCertifications": ["CPR", "BLS"]
  }
}
```

<Warning>
  Contrary to the `any` operator, the `all` operator checks for **complete** intersection for array datatypes.
</Warning>

## Text Search Operators

### Match (`match`)

Performs full-text matching on symbol data types with multiple matching strategies and optional fuzziness. Useful for flexible text-based filtering across search, validation, and processing scenarios.

**Supported Data Types**: [Text Types](/explanation/data-types/base-types#text-and-string-types) (`symbol`)

```json theme={null}
{
  "match": {
    "propertyKey": {
      "value": "search text",
      "type": "word|wordPrefix|phrase|phrasePrefix",
      "fuzziness": 0
    }
  }
}
```

**Match Types**:

* `word`: Matches text that contain the query (order independent)
* `wordPrefix`: Matches text that start with the query (order independent)
* `phrase`: Matches text in the exact order specified
* `phrasePrefix`: Matches text in order with the last word as a prefix

Fuzziness controls how many single-character edits (insertions, deletions, substitutions, or transpositions) are tolerated while still considering a token a match. The [possible values](/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition#body-match-key-fuzziness) are:

* `0` - No typos allowed; use for IDs, exact names, or when precision is critical.
* `1` - Allows one typo per token; good default for short queries that may include minor misspellings.
* `2` - Allows two typos per token; increases recall for longer queries with potential misspellings.
* `3` - Maximum tolerance; use for long queries where errors are more likely, acknowledging reduced precision.

**Examples**:

```json theme={null}
// Word search
{
  "match": {
    "description": {
      "value": "diabetes treatment",
      "type": "word"
    }
  }
}

// Phrase search with fuzziness
{
  "match": {
    "title": {
      "value": "chest pain symptoms",
      "type": "phrase",
      "fuzziness": 1
    }
  }
}
```

## Semantic Operators

### KNN (`knn`)

Performs k-nearest neighbor matching using vector embeddings for semantic similarity. Essential for AI-powered content matching, recommendation systems, and intelligent record selection.

**Supported Data Types**: Vector fields (created by [vectorizer processors](/explanation/ingestion-pipeline/built-in-processors#vectorizer))

```json theme={null}
{
  "knn": {
    "vectorPropertyKey": {
      "value": "semantic query text"
    }
  }
}
```

**Example**:

```json theme={null}
{
  "knn": {
    "content.chunks.vector": {
      "value": "cardiac symptoms and chest pain"
    }
  }
}
```

<Note>
  You do not have to specify model at query time. The system will automatically use the model associated with the enriched vector field, ensuring semantic consistency.
</Note>

## Spatial Operators

### Geo Distance (`geoDistance`)

Tests if a geopoint lies within a specified radius, in meters, from a given location. Supports both coordinate objects and string representations.

**Supported Data Types**: [Geographic Types](/explanation/data-types/base-types#other-primitive-types) (`geopoint`)

```json theme={null}
{
  "geoDistance": {
    "propertyKey": {
      "coordinates": {
        "latitude": 45.0,
        "longitude": -73.0
      },
      "radius": 20000
    }
  }
}
```

**Examples**:

```json theme={null}
// Using coordinate object
{
  "geoDistance": {
    "location": {
      "coordinates": {
        "latitude": 45.5017,
        "longitude": -73.5673
      },
      "radius": 10000
    }
  }
}

// Using string coordinates
{
  "geoDistance": {
    "position": {
      "coordinates": "45.5017,-73.5673",
      "radius": 5000
    }
  }
}
```

## Logical Operators

### And (`and`)

Combines multiple operators where all conditions must be true. Acts as a logical AND junction.

```json theme={null}
{
  "and": [
    { "eq": { "status": "active" } },
    { "gt": { "age": 18 } }
  ]
}
```

### Or (`or`)

Combines multiple operators where at least one condition must be true. Acts as a logical OR junction.

```json theme={null}
{
  "or": [
    { "eq": { "department": "Cardiology" } },
    { "eq": { "department": "Emergency" } }
  ]
}
```

### Not (`not`)

Negates another operator, returning records that do NOT match the specified condition.

```json theme={null}
{
  "not": {
    "eq": {
      "status": "inactive"
    }
  }
}
```

## Composite Operators

### Composite (`composite`)

Applies multiple operators within a specific nested data structure or traversed property path. Essential for querying related data without joins.

```json theme={null}
{
  "composite": {
    "nestedPropertyPath": [
      { "eq": { "nestedPropertyPath.field1": "value1" } },
      { "gt": { "nestedPropertyPath.field2": 100 } }
    ]
  }
}
```

**Example**:

```json theme={null}
{
  "composite": {
    "resources.observation": [
      {
        "eq": {
          "resources.observation.patientId.value": "PAT-12345"
        }
      },
      {
        "eq": {
          "resources.observation.status": "final"
        }
      }
    ]
  }
}
```

## Platform Integration Examples

### Data Partition API - Record Filtering

Using operators to filter records in data partition queries:

```json theme={null}
{
  "filter": {
    "and": [
      {
        "eq": {
          "status": "active"
        }
      },
      {
        "gt": {
          "lastModified": "2024-01-01T00:00:00Z"
        }
      }
    ]
  }
}
```

### Registry API - Field Validation

Defining validation rules for data fields:

```json {collectForTests=profile} theme={null}
{
  "properties": {
    "name": {
      "type": "symbol"
    },
    "practiceNumber": {
      "type": "integer"
    },
    "specialities": {
      "type": "array",
      "rules": [
        {
          "required": true,
          "min": 1,
          "when": {
            "eq": {
              "practiceNumber": "*" // Wildcard to test for the presence of a value
            }
          }
        }
        // Additional rules can be specified here (they can also contain their own `when` clauses)
      ],
      "items": {
        "type": "symbol"
      }
    }
  }
}
```

See [Field Validation](/explanation/field-validation/advanced#conditional-rules) for more details.

### Registry API - Ingestion Pipeline Conditions

Applying conditional logic in data processing pipelines:

```json theme={null}
{
  "steps": [
    {
      "type": "VECTORIZER",
      "vectorizer": {
        "inputProperty": "description",
        "modelId": "text-embedding-004",
        "propertyKey": "vector",
        "provider": "google",
        "dimensions": 768
      },
      "trigger": {
        "type": "OPERATOR_TRIGGER",
        "operator": {
          "and": [
            {
              "eq": {
                "status": "published"
              }
            },
            {
              "gt": {
                "lastModified": "2024-01-01T00:00:00Z"
              }
            }
          ]
        }
      }
    }
  ]
}
```

See [Triggers](/explanation/ingestion-pipeline/basics#triggers) for more details.

### Data Partition API - Search

Combining semantic and exact matching operators for comprehensive filtering.

For more details, see the [Search API documentation](/explanation/search).

```json theme={null}
{
  "and": [
    {
      "or": [
        {
          "knn": {
            "specialties.vector": {
              "value": "cardiac rehabilitation"
            }
          }
        },
        {
          "match": {
            "name.given": {
              "value": "Dr. Smith",
              "type": "wordPrefix"
            }
          }
        }
      ]
    },
    {
      "geoDistance": {
        "location": {
          "coordinates": {
            "latitude": 45.5017,
            "longitude": -73.5673
          },
          "radius": 25000
        }
      }
    }
  ]
}
```

## Related Concepts

<CardGroup cols={2}>
  <Card title="Data Types" icon="database" href="/explanation/data-types/base-types">
    Understanding supported data types for each operator
  </Card>

  <Card title="Semantic Search" icon="brain" href="/explanation/semantic-search">
    Deep dive into vector-based matching capabilities
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/api-reference/search/search-resources-of-a-specific-collection-in-the-data-partition">
    Using operators in search queries
  </Card>

  <Card title="Data Ingestion" icon="upload" href="/explanation/ingestion-pipeline/basics#triggers">
    Applying operators in processing pipelines
  </Card>
</CardGroup>