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.
Filter vs search¶
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:
| 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 }
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:
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
}
}
}
}
}'