Skip to content

docs: clarity/consistency comments on design.md and L1-L4 docs #175

Description

@milindsrivastava1997

Review comments on the docs in docs/. Grouped by file, with line numbers.

docs/design.md

  • L20 — Give an example of what "language's own native representation" means.
  • L20 — The "L1 - query language" section title is ambiguous: unclear whether "query language" describes the input of L1, the output of L1, or what L1 does. Same ambiguity applies to the other layer section titles.
  • L51 — Unclear what "column references vs schema positions" means.
  • L80 — "Deployment here refers to ..." — move term definitions like this out to a separate glossary section instead of inline.
  • L85 — What does "row identity" mean, and how does it relate to cross-query sharing?
  • L99 — This could be written much more readably, e.g.: "This layer decides whether to use summaries for an intent. If yes, what summaries to use and how. This includes picking a summary family to use (link to sketch kind in asap_sketchlib) and its configuration parameters. ..."
  • L120 — Claims it is assigning each piece node of a summary-bound L4 plan to physical execution. This is contradicted a few lines later, which says there is no planner, just an interface.
  • L150 — "summary-bound plan" or "summary-bound physical plan"? Terms must be consistent — assuming this refers to L5, not L4?
  • L152 — Unclear what purpose this sentence serves: "Reality can diverge from the plan in ways planning time never sees."

docs/l1-query-language.md

  • L19 — What does this subsection title mean?
  • L24 — Unclear what this sentence means.
  • L28 — Why are we discussing L2 and L3 here?
  • L46 — Same issue as L28.
  • L54 — Very confusing — what is "the contract" referring to?
  • L89 — Why are we discussing L3 here?

docs/l2-logical-plan.md

  • General: it's unclear whether "L2" refers to an object or a process — is L2 the description of some IR, or the process of converting one IR into another? (Same ambiguity applies to the other layers.)
  • L15 — Before this point, it's unclear what the output of this layer is.
  • L22 — The open-vs-closed schema problem should be introduced explicitly with an example first, then explain how it's handled. Currently the problem statement and the handling are mixed together.
  • L32 — What does "purely structural and total" mean?

docs/l3-intent-algebra.md

  • L11 — What is the output of this layer?
  • L44 — Unclear what the difference is between the "intent vocabulary" and "intent catalog" sections.

docs/l4-summary-bound-ir.md

  • L12 — Why are we talking about execution here?
  • L18 — Unclear what this means.
  • L216 — Tree or DAG? Be precise.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions