From 3f1e4a70852a7a79d984c69d5397f73e89556d87 Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Mon, 5 Oct 2026 11:41:03 -0500 Subject: [PATCH 1/5] docs(faq): frame the definition language as Python-hosted but not Python syntax --- src/explanation/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/explanation/faq.md b/src/explanation/faq.md index 054cd0fc..09cd76fe 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -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. DataJoint is implemented in Python, but the definition language does not rely on Python syntax: a definition is parsed by DataJoint itself, not by the Python interpreter. Nothing in it ties it to Python, so the same definitions could be supported by implementations in other languages. ### Composite Primary Keys: A Clarity Comparison @@ -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** | Does not rely on Python syntax; DataJoint parses it, not the Python interpreter, so it is not tied to Python | | **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. From a51af2b7fe1b0e94ad74f1d9e2530c81af48101a Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Mon, 5 Oct 2026 11:56:35 -0500 Subject: [PATCH 2/5] docs(faq): extend language independence to query operations; tighten wording --- src/explanation/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/explanation/faq.md b/src/explanation/faq.md index 09cd76fe..883a9063 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -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. DataJoint is implemented in Python, but the definition language does not rely on Python syntax: a definition is parsed by DataJoint itself, not by the Python interpreter. Nothing in it ties it to Python, so the same definitions could be supported by implementations in other languages. +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 neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. The same definitions and operations could therefore be supported by implementations in other languages. ### Composite Primary Keys: A Clarity Comparison @@ -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** | Does not rely on Python syntax; DataJoint parses it, not the Python interpreter, so it is not tied to Python | +| **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. From aef817c81e04eb2a1b83f1779f9bc6d4a29678a5 Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Mon, 5 Oct 2026 11:56:50 -0500 Subject: [PATCH 3/5] docs(faq): other languages can be supported as necessary --- src/explanation/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/explanation/faq.md b/src/explanation/faq.md index 883a9063..4f089fbc 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -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. The DataJoint Library is implemented in Python, but neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. The same definitions and operations could therefore be supported by implementations in other languages. +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 neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. Therefore, other languages can be supported as necessary. ### Composite Primary Keys: A Clarity Comparison From 1ae51e3437510dfab939e69fdd2ff6511425a1cb Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Mon, 5 Oct 2026 11:57:30 -0500 Subject: [PATCH 4/5] Revert "docs(faq): other languages can be supported as necessary" This reverts commit aef817c81e04eb2a1b83f1779f9bc6d4a29678a5. --- src/explanation/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/explanation/faq.md b/src/explanation/faq.md index 4f089fbc..883a9063 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -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. The DataJoint Library is implemented in Python, but neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. Therefore, other languages can be supported as necessary. +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 neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. The same definitions and operations could therefore be supported by implementations in other languages. ### Composite Primary Keys: A Clarity Comparison From ce91738001cfb7fe9371531531fd3c2b315d3382 Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Fri, 16 Oct 2026 10:03:36 -0500 Subject: [PATCH 5/5] faq: queries are compiled into SQL, though written with Python operators The paragraph said query operations rely on neither Python syntax nor Python data structures. They use both: the algebra overloads Python operators, and restrictions take dicts and other Python values. What holds is that queries are compiled into SQL rather than executed in Python, and that the algebra, like the definition language, is independent of the host language. --- src/explanation/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/explanation/faq.md b/src/explanation/faq.md index 883a9063..f3b24daf 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -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. The DataJoint Library is implemented in Python, but neither its data definitions nor its query operations rely on Python syntax or Python data structures: definitions are parsed by DataJoint itself, and queries are compiled into SQL against the schema. The same definitions and operations could therefore be supported by implementations in other languages. +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