Skip to content

docs(faq): the definition language is not Python syntax #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dimitri-yatsenko wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs(faq): the definition language is not Python syntax #297

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3f1e4a7
docs(faq): frame the definition language as Python-hosted but not Pyt…
dimitri-yatsenko Oct 5, 2026
a51af2b
docs(faq): extend language independence to query operations; tighten …
dimitri-yatsenko Oct 5, 2026
aef817c
docs(faq): other languages can be supported as necessary
dimitri-yatsenko Oct 5, 2026
1ae51e3
Revert "docs(faq): other languages can be supported as necessary"
dimitri-yatsenko Oct 5, 2026
ce91738
faq: queries are compiled into SQL, though written with Python operators
dimitri-yatsenko Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/explanation/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ DataJoint provides a custom data definition language and [query algebra](query-a

### The Definition Language

DataJoint's [definition language](../reference/specs/table-declaration.md/) is a standalone scripting language for declaring table schemas — not Python syntax embedded in strings. It is designed for uniform support across multiple host languages (Python, MATLAB, and potentially others). The same definition works identically regardless of which language you use.
DataJoint's [definition language](../reference/specs/table-declaration.md/) is a standalone scripting language for declaring table schemas — not Python syntax embedded in strings. The DataJoint Library is implemented in Python, but its data definitions are parsed by DataJoint rather than the Python interpreter, and its queries are compiled into SQL rather than executed in Python. Queries are written with Python operators (`&`, `-`, `*`) and Python values such as dicts, but the query algebra they express is independent of the host language, as is the definition language. The same definitions and operations could therefore be supported by implementations in other languages.

### Composite Primary Keys: A Clarity Comparison

Expand Down Expand Up @@ -67,7 +67,7 @@ All in two characters. As pipelines grow to dozens of tables with deep dependenc
| **Readable** | Looks like a specification: `---` separates primary from secondary attributes, `#` for comments |
| **Concise** | `mouse_id : int32` vs `mouse_id = Column(Integer, primary_key=True)` |
| **Database-first** | `table.describe()` shows the same format; virtual schemas reconstruct definitions from database metadata |
| **Language-agnostic** | Same syntax for Python, MATLAB, future implementations |
| **Language-agnostic** | Parsed by DataJoint, not the Python interpreter — nothing in it is Python-specific |
| **Separation of concerns** | Definition string = structure (what); class = behavior (how: `make()` methods) |

The definition string **is** the specification — a declarative language that describes entities and their relationships, independent of any host language's syntax.
Expand Down