fpt-query

Querying and reporting on ShotGrid

Applies to any FPT site and entity type, not one project's pipeline. This is the read side: it cannot damage the database, so the failure modes are wrong answers and exhausted context, not lost work.

For filter operators, method signatures and pagination syntax use search_sg_docs — that is the reference layer and it covers all three APIs. This skill is which question deserves which tool, and what a plausible answer hides.

The failure that looks like an answer

A single-entity check is not a state check

Asking "is ShotGrid clean?" and querying only Version returned clean in-vivo while PublishedFile rows from the same operation were still there. The answer was confidently wrong.

Enumerate every entity type the operation writes before declaring state. A publish touches PublishedFile, usually Version, sometimes Attachment and the Task status. A cleanup check that covers one of them is not a check.

Same rule for "did it work?" — verify the entity you created, not a neighbour that happens to exist.

Aggregate on the server

fpt_reporting(action="summarize") does count / sum / avg / min / max with grouping, server-side. Reach for it whenever the question is a number or a breakdown:

• "how many shots per status" → summarize + grouping, one small payload.
• sg_find then counting rows in your head → pulls every row into context to throw them away. For a few hundred shots this is the difference between a 200-token answer and a 40,000-token one.

Use sg_find when the user needs the rows themselves, not a statistic.

Field discipline

Every field you name is paid once per row. Name only the fields you will actually read or show; never pass a field list harvested from sg_schema wholesale. Set a real limit — an exploratory query is 5–20 rows, not the default.

If you do not know the result size, summarize the count first, then decide whether to fetch rows at all.