Skip to main content

ExplainPlanRequest

concept objectrequired

The authored concept body. Stored as JSONB in the definitions table with definition_type='concept'.

Primitives declare the data sources the concept depends on (names and expected types). Features define the DAG of operators that transform primitive data into the concept's output value.

output_feature names the terminal FeatureNode in the DAG — the node whose inferred output type must match output_type. The compiler validates this.

For categorical concepts, labels declares the closed label set. The type checker enforces that all execution paths produce only declared labels.

Immutability: once registered under (concept_id, version), the body is frozen. Semantic changes require a new version.

concept_idConcept Id (string)required
versionVersion (string)required
namespaceNamespace (string)required

Possible values: [personal, team, org, global]

output_typeOutput Type (string)required
labels object
anyOf
  • Array [
    • string
  • ]
    • description object
    anyOf
    string
    primitives objectrequired
    property name* PrimitiveRef

    A primitive data source referenced within a concept definition.

    Specifies the expected Memintel type of the primitive and how to handle missing data. The actual source configuration (connector, SQL query, etc.) lives in the registered primitive config (memintel.config.md / PrimitiveConfig) — this ref only declares the contract the concept author expects.

    missing_data_policy resolves output nullability at compile time: None / 'null' → T? (null propagates) 'zero' → T (null replaced with 0) 'forward_fill' → T (null replaced with last known value) 'backward_fill' → T (null replaced with next known value)

    labels must be declared when type is 'categorical'. The compiler validates that all execution paths produce only the declared labels (§5 of type spec).

    typeType (string)required
    missing_data_policy object
    anyOf
    MissingDataPolicy (string)

    Policy applied when a primitive fetch returns no data for an entity.

    null — return null (T?); downstream operators must handle nullable zero — substitute 0; forces non-nullable output forward_fill — use last known value (non-nullable) backward_fill — use next known value (non-nullable)

    Specified per-request to override per-primitive defaults.

    Possible values: [null, zero, forward_fill, backward_fill]

    labels object
    anyOf
  • Array [
    • string
  • ]
    • features objectrequired
    property name* FeatureNode

    A single authored operator node in a concept's feature DAG.

    This is the authored representation — it mirrors the YAML format used in concept definitions. The inputs dict maps each operator input slot name to either a primitive name (e.g. 'user.activity_count') or another feature name in this concept (e.g. 'activity_drop').

    The compiler resolves symbolic names to upstream node_ids when producing GraphNode. output_type is NOT set by the author — it is inferred by the type checker during compilation.

    params carries operator-specific parameters (e.g. {'window': '30d'} for pct_change or moving_average). Duration values must follow the format: positive integer + suffix (h/d/w/m/y). E.g. '30d', '4w'.

    opOp (string)required
    inputsobjectrequired
    paramsobject
    output_featureOutput Feature (string)required
    created_at object
    anyOf
    string<date-time>
    deprecatedDeprecated (boolean)
    Default value: false
    ExplainPlanRequest
    {
      "concept": {
        "concept_id": "string",
        "version": "string",
        "namespace": "personal",
        "output_type": "string",
        "labels": [
          "string"
        ],
        "description": "string",
        "primitives": {},
        "features": {},
        "output_feature": "string",
        "created_at": "2024-07-29T15:51:28.071Z",
        "deprecated": false
      }
    }