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, relationships, or objects, 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, relationships, or objects)
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	Test numerical, date or code value relationships	`eq`, `lt`, `gt`	Status checks, date ranges, numerical thresholds
Collection	Work with arrays and multiple values	`any`, `all`	Multi-select filters, requirement validation
Text Search	Handle textual content with various matching strategies	`match`	Full-text search, content filtering
Semantic	Enable AI-powered similarity matching	`knn`	Content recommendations, semantic search
Spatial	Support location-based filtering	`geoDistance`	Proximity searches, geographic boundaries
Logical	Combine multiple conditions	`and`, `or`, `not`	Complex filtering logic, condition composition
Composite	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, Temporal Types, Integer, Decimal, Boolean, Geographic Types

{
  "eq": {
    "propertyKey": "value"
  }
}

Examples:

// Exact match
{
  "eq": {
    "status": "active"
  }
}

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

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

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.

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 (symbol, code, markdown), Temporal Types (date, datetime, time, instant), Numeric Types (integer, decimal)

{
  "lt": {
    "propertyKey": "value"
  }
}

Examples:

// 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 (symbol, code, markdown), Temporal Types (date, datetime, time, instant), Numeric Types (integer, decimal)

{
  "gt": {
    "propertyKey": "value"
  }
}

Examples:

// 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, Temporal Types, Integer, Decimal, Boolean, Geographic Types, Array Types

{
  "any": {
    "propertyKey": ["value1", "value2", "value3"]
  }
}

Example:

{
  "any": {
    "specialties": ["Cardiology", "Internal Medicine", "Family Medicine"]
  }
}

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.

All (`all`)

Tests if an enumerable property contains all of the given values. Uses equality comparison for each value. Supported Data Types: Text Types, Temporal Types, Integer, Decimal, Boolean, Geographic Types, Array Types

{
  "all": {
    "propertyKey": ["value1", "value2"]
  }
}

Example:

{
  "all": {
    "requiredCertifications": ["CPR", "BLS"]
  }
}

Contrary to the any operator, the all operator checks for complete intersection for array datatypes.

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 (symbol)

{
  "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

Examples:

// 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)

{
  "knn": {
    "vectorPropertyKey": {
      "value": "semantic query text"
    }
  }
}

Example:

{
  "knn": {
    "content.chunks.vector": {
      "value": "cardiac symptoms and chest pain"
    }
  }
}

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.

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 (geopoint)

{
  "geoDistance": {
    "propertyKey": {
      "coordinates": {
        "latitude": 45.0,
        "longitude": -73.0
      },
      "radius": 20000
    }
  }
}

Examples:

// 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.

{
  "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.

{
  "or": [
    { "eq": { "department": "Cardiology" } },
    { "eq": { "department": "Emergency" } }
  ]
}

Not (`not`)

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

{
  "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.

{
  "composite": {
    "nestedPropertyPath": [
      { "eq": { "nestedPropertyPath.field1": "value1" } },
      { "gt": { "nestedPropertyPath.field2": 100 } }
    ]
  }
}

Example:

{
  "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:

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

Registry API - Field Validation

Defining validation rules for data fields:

{
  "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 for more details.

Registry API - Ingestion Pipeline Conditions

Applying conditional logic in data processing pipelines:

TODO: add example

Data Partition API - Search

Combining semantic and exact matching operators for comprehensive filtering. For more details, see the Search API documentation.

{
  "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
        }
      }
    }
  ]
}

Data Types

Understanding supported data types for each operator

Semantic Search

Deep dive into vector-based matching capabilities

Search API

Using operators in search queries

Data Ingestion

Applying operators in processing pipelines

About Clinia

Core Concepts

Search

Configuring Data Sources

Configuring Partitions

Managing Data

Master Data Management

Terminology

Identity and Access Management

Agents

​Operators

​Understanding Operators

​Where Operators Are Used

​Data Partition API

​Registry API

​Operator Categories

​Comparison Operators

​Equal (eq)

​Less Than (lt)

​Greater Than (gt)

​Collection Operators

​Any (any)

​All (all)

​Text Search Operators

​Match (match)

​Semantic Operators

​KNN (knn)

​Spatial Operators

​Geo Distance (geoDistance)

​Logical Operators

​And (and)

​Or (or)

​Not (not)

​Composite Operators

​Composite (composite)

​Platform Integration Examples

​Data Partition API - Record Filtering

​Registry API - Field Validation

​Registry API - Ingestion Pipeline Conditions

​Data Partition API - Search

​Related Concepts

Data Types

Semantic Search

Search API

Data Ingestion

Operators

Understanding Operators

Where Operators Are Used

Data Partition API

Registry API

Operator Categories

Comparison Operators

Equal (`eq`)

Less Than (`lt`)

Greater Than (`gt`)

Collection Operators

Any (`any`)

All (`all`)

Text Search Operators

Match (`match`)

Semantic Operators

KNN (`knn`)

Spatial Operators

Geo Distance (`geoDistance`)

Logical Operators

And (`and`)

Or (`or`)

Not (`not`)

Composite Operators

Composite (`composite`)

Platform Integration Examples

Data Partition API - Record Filtering

Registry API - Field Validation

Registry API - Ingestion Pipeline Conditions

Data Partition API - Search

Related Concepts