Skip to content

Search and filter

AIGr.id has one query language for finding things across all of its registries: clusters, blocks, components, vDAGs, policies and their metrics. The same language is used when you search directly, when block placement policies shortlist clusters, when vDAG assignment policies find blocks, and when the inference server picks a block for you.

At a glance

Filter (POST /api/filter): returns everything that matches your conditions.
Search (POST /api/search): filters first, then runs a ranking policy that refines the results, down to a top-K list or a single best match.
Served by: the search server (search-server, NodePort 30150), through the Parser.

flowchart LR
    Q["Conditions"] --> F["Filter<br/><small>across databases</small>"]
    F -->|"/api/filter"| R1["All matches"]
    F -->|"/api/search"| P{{"Ranking policy<br/>(your Python)"}}
    P --> R2["Refined results<br/><small>top-K or best match</small>"]
Filter Search
How Declarative conditions, translated into each database's own query language. A filter, followed by your ranking policy.
Returns Every matching record. Whatever your policy returns.
Use when The conditions alone are enough. You need logic that conditions can't express, such as scoring, ranking or calling other services.

Filter query language

A filter is a JSON tree of conditions. Field names use dot notation for nested fields (gpus.memory, clusterMetadata.vendor).

Simple condition

Compares one field with a value:

{
  "variable": "<field_name>",
  "operator": "<comparison_operator>",
  "value": <comparison_value>
}
Operator Meaning
== Equal to
IN Value is in the given list
> / >= Greater than / greater than or equal
< / <= Less than / less than or equal
LIKE Pattern match, with * as a wildcard

Logical condition

Combines conditions, which may themselves be nested:

{
  "logicalOperator": "AND" | "OR",
  "conditions": [
    { <simple_condition or logical_condition> },
    ...
  ]
}
Operator Meaning
AND All conditions must be true.
OR At least one condition must be true.

Examples

These examples filter cluster records.

// Region equals us-west-2
{ "variable": "regionId", "operator": "==", "value": "us-west-2" }

// Reputation above 90
{ "variable": "reputation", "operator": ">", "value": 90 }

// Tagged "ml" or "vision"
{ "variable": "tags", "operator": "IN", "value": ["ml", "vision"] }

// At least 128 GB of RAM (sizes are in MB)
{ "variable": "memory", "operator": ">=", "value": 131072 }

// ID contains "vision"
{ "variable": "id", "operator": "LIKE", "value": "*vision*" }

// Nested field: more than 48 GB of GPU memory
{ "variable": "gpus.memory", "operator": ">", "value": 49152 }
{
  "logicalOperator": "AND",
  "conditions": [
    { "variable": "regionId", "operator": "==", "value": "us-west-2" },
    { "variable": "reputation", "operator": ">", "value": 90 }
  ]
}
{
  "logicalOperator": "AND",
  "conditions": [
    { "variable": "regionId", "operator": "==", "value": "us-west-2" },
    {
      "logicalOperator": "OR",
      "conditions": [
        { "variable": "tags", "operator": "IN", "value": ["ml"] },
        { "variable": "reputation", "operator": ">=", "value": 95 }
      ]
    }
  ]
}

What you can query

Query key Searches
clusterQuery Cluster records
clusterMetricsQuery Live cluster metrics
blockQuery Running blocks
blockMetricsQuery Live block metrics
componentQuery Registered components
vdagQuery vDAGs
vdagMetricsQuery Live vDAG metrics
policyQuery Registered policies
policyFunctionQuery Deployed policy functions
policyGraphQuery Policy graphs

Combining queries

You can combine several queries in one request. Some are applied in order, with the results of one narrowing the next:

To find... (matchType) Queries applied, in order
block clusterQuery → blockQuery → blockMetricsQuery (optional)
cluster clusterMetricsQuery (optional) → clusterQuery
vdag vdagMetricsQuery (optional) → vdagQuery
component componentQuery
policy / policyFunction / policyGraph policyQuery / policyFunctionQuery / policyGraphQuery

For example, when you give both a clusterQuery and a blockQuery, the system finds the matching clusters first, then automatically adds this condition to the block query:

{
  "variable": "cluster.id",
  "operator": "IN",
  "value": [<cluster_ids>]
}

Metrics queries work the same way, as pre-filters for their entity.


Filter request

The request body (body.values):

Field Type Required Description
matchType string Yes The kind of entity to return: block, cluster, vdag, component, policy, policyFunction or policyGraph.
filter object Yes One or more <entity>Query keys, each with a condition tree.

Example: blocks with reputation above 80, in clusters in us-west-2:

{
  "matchType": "block",
  "filter": {
    "clusterQuery": {
      "variable": "regionId",
      "operator": "==",
      "value": "us-west-2"
    },
    "blockQuery": {
      "variable": "reputation",
      "operator": ">",
      "value": 80
    }
  }
}

Send it with /api/filter:

curl -X POST http://<parser-url>/api/filter \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "templateUri": "Parser/V1",
      "parameters": {}
    },
    "body": {
      "values": {
        "matchType": "cluster",
        "filter": {
          "clusterQuery": {
            "logicalOperator": "AND",
            "conditions": [
              {
                "variable": "regionId",
                "operator": "==",
                "value": "us-west-2"
              },
              {
                "variable": "status",
                "operator": "==",
                "value": "live"
              }
            ]
          }
        }
      }
    }
  }'

Search request

The request body (body.values):

Field Type Required Description
matchType string Yes The kind of entity to return.
rankingPolicyRule.policyRuleURI string Yes Your ranking policy.
rankingPolicyRule.settings object No Settings for the policy.
rankingPolicyRule.parameters.filterRule object Yes The filter to run first: a matchType and a filter, as above.
rankingPolicyRule.parameters.return number No How many top results to return.
rankingPolicyRule.parameters.<anything> any No Any other parameters your policy needs.

Writing a ranking policy

The policy receives the filter results as input_data (a list of records) and returns the refined results:

class AIOSv1PolicyRule:
    def __init__(self, rule_id, settings, parameters):
        self.rule_id = rule_id
        self.settings = settings
        self.parameters = parameters

    def eval(self, parameters, input_data, context):
        """
        input_data: list of records returned by the filter step
        """
        # Refine, rank or pick here

        # Return the new results
        return []

Example: keep only clusters with at least a minimum reputation, optionally in one region.

class AIOSv1PolicyRule:
    def __init__(self, rule_id, settings, parameters):
        self.rule_id = rule_id
        self.settings = settings
        self.parameters = parameters

    def eval(self, parameters, input_data, context):
        """
        Args:
            parameters (dict):
                - "minReputation" (int): minimum reputation required.
                - "region" (optional str): regionId to restrict the search to.
            input_data (list): cluster records returned by the filter step.
            context (dict): shared cache (not used here).

        Returns:
            list: the clusters that pass.
        """
        min_reputation = parameters.get("minReputation", 90)
        target_region = parameters.get("region", None)

        result = []
        for cluster in input_data:
            if cluster.get("reputation", 0) >= min_reputation:
                if target_region:
                    if cluster.get("regionId") == target_region:
                        result.append(cluster)
                else:
                    result.append(cluster)

        return result

Register it with the Policies System (how), then send a search with /api/search:

curl -X POST http://<parser-url>/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "templateUri": "Parser/V1",
      "parameters": {}
    },
    "body": {
      "values": {
        "matchType": "cluster",
        "rankingPolicyRule": {
          "policyRuleURI": "policies.search.cluster-reputation-filter:v0.0.01-beta",
          "settings": {},
          "parameters": {
            "filterRule": {
              "matchType": "cluster",
              "filter": {
                "clusterQuery": {
                  "logicalOperator": "AND",
                  "conditions": [
                    {
                      "variable": "regionId",
                      "operator": "==",
                      "value": "us-west-2"
                    },
                    {
                      "variable": "status",
                      "operator": "==",
                      "value": "live"
                    }
                  ]
                }
              }
            },
            "minReputation": 90
          }
        }
      }
    }
  }'