research / wire operation
Screen a universe
totalfinance.research.screen
Filter a point-in-time universe of instrument observations with a declarative filter tree, order the survivors, and optionally limit them — a replayable screen by construction (no caller predicate crosses the wire). The result is screenUniverse(...) verbatim.
| Pack / profiles | research / full, research |
|---|---|
| Default discovery | Opt-in |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | medium / Do not assume inline interruption |
| Handle-eligible inputs | None |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"universeId": {
"type": "string",
"minLength": 1
},
"asOf": {
"type": "number",
"description": "Epoch ms; the latest observation at or before it is used per instrument"
},
"observations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"availableTimestampMs": {
"type": "number"
},
"fields": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"description": "Declared fields only; null is a stated missing value"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"availableTimestampMs",
"fields"
]
}
},
"fieldDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fieldName": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"numeric",
"category",
"text",
"boolean"
]
},
"unit": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"fieldName",
"kind"
]
},
"minItems": 1
},
"filter": {
"$id": "https://totalfinance.dev/schemas/research/screen-filter",
"oneOf": [
{
"type": "object",
"properties": {
"all": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "https://totalfinance.dev/schemas/research/screen-filter"
}
}
},
"required": [
"all"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"any": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "https://totalfinance.dev/schemas/research/screen-filter"
}
}
},
"required": [
"any"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"not": {
"$ref": "https://totalfinance.dev/schemas/research/screen-filter"
}
},
"required": [
"not"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string",
"enum": [
"greaterThan",
"greaterThanOrEqual",
"lessThan",
"lessThanOrEqual"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"operator",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string",
"enum": [
"equals",
"notEquals"
]
},
"value": {
"type": [
"number",
"string",
"boolean"
]
}
},
"required": [
"field",
"operator",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string",
"enum": [
"between"
]
},
"from": {
"type": "number"
},
"to": {
"type": "number"
}
},
"required": [
"field",
"operator",
"from",
"to"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string",
"enum": [
"in",
"notIn"
]
},
"values": {
"type": "array",
"minItems": 1,
"items": {
"type": [
"number",
"string"
]
}
}
},
"required": [
"field",
"operator",
"values"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string",
"enum": [
"isPresent",
"isMissing"
]
}
},
"required": [
"field",
"operator"
],
"additionalProperties": false
}
],
"description": "Complete ScreenFilter grammar (executable examples: docs/guides/dogfood-journeys.md): ordering operators greaterThan | greaterThanOrEqual | lessThan | lessThanOrEqual require numeric value; equals | notEquals use a number/string/boolean value. No gt/gte aliases. A ScreenFilter tree — { all: [...] } | { any: [...] } | { not: ... } | { field, operator, value } | { field, operator: 'between', from, to } | { field, operator: 'in' | 'notIn', values } | { field, operator: 'isPresent' | 'isMissing' } — validated node by node by screenUniverse; omitted = every eligible row passes"
},
"missingValuePolicy": {
"type": "string",
"enum": [
"exclude",
"evaluate-as-false"
]
},
"orderBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"direction": {
"type": "string",
"enum": [
"ascending",
"descending"
]
}
},
"additionalProperties": false,
"required": [
"field",
"direction"
]
}
},
"limit": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"universeId",
"asOf",
"observations",
"fieldDefinitions",
"missingValuePolicy",
"orderBy"
]
}Output schema
{
"type": "object",
"properties": {
"assumptions": {
"type": "object",
"description": "Applied conventions"
},
"diagnostics": {
"type": "object",
"description": "Engine, method, warnings"
},
"rows": {
"type": "array",
"items": {
"type": "object"
},
"description": "{ instrumentId, availableTimestampMs, fields }"
}
},
"required": [
"assumptions",
"diagnostics",
"rows"
]
}