AlmondTill/G3N API

On this page

searchPlanRun

query · in the family Reading your records

What it does

Run a search plan — start at one kind of record, follow its links to related records step by step, and read the last step’s matches newest first.

Run ONE search plan synchronously, as you, inside your tenant: start at a plan-searchable family with optional filter clauses (the FilterInput grammar VERBATIM), hop along KNOWN relationships (outbound follows a reference field of the current family to the family it names; inbound walks a referring family and keeps the rows whose reference names a current match — at most 3 hops, each with its own clauses against ITS family), and answer the LAST step's rows as six-field summaries — newest first (updatedAt desc, id tiebreak), up to limit (1..200; absent = 100) — with the EXACT matchCount, the records examined, the elapsed ms, the plan in words, and the estimate the run made before reading anything. THE PLAN GATE refuses BEFORE any read — an unknown family, a field outside its roster, a hop that is not a relationship of the current family — naming the legal words. the budget rule refuses a plan that would examine more than 5000 records (measured KEYS ONLY before the first read), a step that matches more than 1000, or a run past 8 s — no partials in this synchronous lane. Every refusal is VALIDATION/INVALID in the teaching voice. AS YOU: a family you may not list refuses the whole plan before any read; the tenant rides every key. A JSON null on an optional input field reads as absent. Requires authentication.

What happens

Read-only and bounded: it runs as you, inside your organization, over records you may already list. A plan that would read too much stops before it starts and tells you what to narrow; nothing is saved.

Who may call it

Capability area: Reading your records — Looking up and listing the records of your organization.

Arguments

NameTypeRequiredNotes
planSearchPlanInput SearchPlanInput!yesNo further notes.

Returns

SearchPlanRun SearchPlanRun! — A finished plan run: the plan in words, the pre-read estimate, the matches newest first up to the limit, the EXACT matchCount, the records examined, the elapsed ms.

Example request

query ExampleSearchPlanRun($plan: SearchPlanInput!) {
  searchPlanRun(plan: $plan) {
    words
    matchCount
    examined
    elapsedMs
  }
}

Variables:

{
  "plan": {
    "start": {
      "family": "<family>",
      "filter": {
        "clauses": [
          {
            "field": "<field>",
            "op": "<op>",
            "values": [
              "<values>"
            ]
          }
        ]
      }
    },
    "hops": [
      {
        "direction": "outbound",
        "field": "<field>",
        "family": "<family>",
        "filter": {
          "clauses": [
            {
              "field": "<field>",
              "op": "<op>",
              "values": [
                "<values>"
              ]
            }
          ]
        }
      }
    ]
  }
}

Example response

{
  "data": {
    "searchPlanRun": {
      "words": "<words>",
      "matchCount": 1,
      "examined": 1,
      "elapsedMs": 1
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer