IF Commons GitHub

AnyFS Query: planning

0003Active

0003-query-planning · owner if · domain commons

Requirements

FR-001checkpassing

Each conjunct of the WHERE MUST be classified as of the listing, when it uses no column that needs a read of the object, or of the content, when it uses text, is_text or redacted; a conjunct is a part of an AND, and an OR or a NOT is one whole.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts, anyfs-query/src/logical/pushdown.ts

Tests: passed: suite/planning.test.ts each conjunct of a filter is of the listing or of the content

Cited by: AnyFS Query, logical/pushdown

FR-002checkpassing

A listing conjunct that is path = '...', path GLOB '...' or under(path, '...') MUST bound where the objects can be: one path, a prefix ending at a whole segment (the literal start of a glob up to its last /), or nowhere where the bounds cannot all hold; LIKE MUST NOT bound, since it ignores case and a prefix does not. A run MUST list below the deepest prefix that is within the prefix of its place, ask stat of one path where the store has it, and ask nothing where the bound is nowhere or does not meet the place.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts, anyfs-query/src/logical/pushdown.ts

Tests: passed: suite/planning.test.ts the operations a query makes follow its bound: a prefix lists below it, one path is a stat; passed: suite/planning.test.ts the paths a filter names say where to list: one path, a prefix, or nowhere

Cited by: AnyFS Query, logical/pushdown

FR-003checkpassing

An object MUST be read only when it has passed every listing conjunct, and no object MUST be read for a query on files.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts

Tests: passed: suite/planning.test.ts an object is read only when the listing has left it

FR-004checkpassing

The rows of a query MUST be the rows of its plan run over every object of the place, whatever was bounded or left unread.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts

Tests: passed: suite/planning.test.ts a query gives the rows of its plan run over every object, whatever is pushed down

FR-005checkpassing

A query with a LIMIT and no ORDER BY and no DISTINCT MUST end its run when it has the rows that the limit and the offset ask for; a query with an ORDER BY MUST read every object that its listing conjuncts leave.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts

Tests: passed: suite/planning.test.ts a limit with no sort ends the run as soon as it has its rows, and a sort reads everything

FR-006checkpassing

An explanation MUST say the plan, the source and the place, what is listed (a prefix, one path or nothing, and the rule that gave it), the listing filters, the content filters and that only the objects the listing leaves are read, the consent needed and the budget, and MUST call no store.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts

Tests: passed: suite/planning.test.ts the explanation says the plan, the place, what is listed, the filters of each kind, the co

FR-007checkpassing

The table revisions MUST be asked of one path (path = '...') and of a store that has history, and a query that does not name one path MUST be a problem that says so; the table places MUST give the places of the context and call no store.

Enforced (check): .github: cd commons/anyfs-query && bun run verify — suite/planning.test.ts

Proved by: anyfs-query/suite/planning.test.ts

Written in: anyfs-query/src/logical/execute.ts

Tests: passed: suite/planning.test.ts the versions of a path are asked of one path and of a store that has history, and places l

Acceptance scenarios

  1. Given ext = 'json' AND contains(text, 'a'), When it is classified, Then the first is of the listing and the second of the content, per FR-001.
  2. Given path GLOB 'machines/al*', When it is bounded, Then the prefix is machines, per FR-002.
  3. Given under(path, 'a') AND under(path, 'b'), When it is run, Then no operation reaches the store, per FR-002.
  4. Given nine objects of which four are small JSON, When a query reads those of 60 bytes or less that contain a word, Then four are read, per FR-003.
  5. Given random conjuncts and orders, When each query is run, Then its rows are those of the plan run over all objects, per FR-004.
  6. Given LIMIT 1 with no sort over a store where the first object matches, When it is run, Then not every object is read, per FR-005.
  7. Given a query, When it is explained, Then the text is as FR-006 says and the store was not called.

Out of scope

  • Joins and aggregates over files (0002-query-language).
  • A statistics catalogue and cost-based choices: the plan has one way to carry out each query.

Edge cases

  • A glob such as *.json has no literal start, so it bounds nothing and the whole place is listed (FR-002).

Assumptions

  • A store lists everything below a prefix in one key space, so a prefix is the only bound a listing can use (FR-002).

Open questions

  • None.

Key entities

  • Bound, Classified filter, Reach, Explanation.

Success criteria

SC-001success criterion

The rows of every random query are tested to equal the rows of its plan run over everything, and the operations a run makes are counted.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

AnyFS Query, logical/execute, logical/pushdown

Titles, headings, exports, tables, columns and requirements. Esc closes.