Skip to content

docs: Add singleton tables documentation#137

Merged
MilagrosMarin merged 18 commits intomainfrom
docs/singleton-tables
Jan 23, 2026
Merged

docs: Add singleton tables documentation#137
MilagrosMarin merged 18 commits intomainfrom
docs/singleton-tables

Conversation

@dimitri-yatsenko
Copy link
Member

@dimitri-yatsenko dimitri-yatsenko commented Jan 22, 2026 •
edited
Loading

Summary

Combined documentation updates:

  1. Singleton tables documentation (feat: Add singleton tables (empty primary keys) datajoint-python#1341)
  2. PostgreSQL compatibility fixes for tutorials
  3. Decimal types for human-entered fields
  4. Terminology standardization

Changes

Singleton Tables

  • table-declaration.md - Added section 2.5 "Singleton Tables (Empty Primary Keys)"
    • Syntax: empty primary key section creates singleton
    • Behavior table (insert, fetch, uniqueness)
    • Use cases
    • Implementation details (hidden _singleton attribute)
  • university.ipynb - Added CurrentTerm singleton example

PostgreSQL Fixes

  • Fix boolean aggregation: sum(correct) → sum(CASE WHEN correct THEN 1 ELSE 0 END)
  • Fix string quoting: use single quotes for string literals in SQL expressions

Type Improvements

  • Change float32 to decimal for manually entered values (weight, duration, frame_rate, reaction_time)
  • Retain float for computed values and measurements
  • Add explicit decimal-to-float conversion in computation code

Documentation

  • Standardize on "secondary attributes" (matches API: heading.secondary_attributes)
  • Address PR Merge pre/v2.1 into main #136 review comments (fetch → to_dicts/to_pandas)
  • Add scripts/execute-notebooks.sh for reproducible notebook execution
  • Removed deprecated ___ separator mention (only --- is supported)

Related

Test Plan

  • All 21 notebooks pass on PostgreSQL backend
  • All 21 notebooks execute without SSL warnings
  • mkdocs site builds and displays correctly

🤖 Generated with Claude Code

dimitri-yatsenko and others added 8 commits January 22, 2026 14:15
@dimitri-yatsenko @claude
docs: Add singleton tables documentation
af17b58 
- Add section 2.5 "Singleton Tables (Empty Primary Keys)" to table-declaration.md
- Update university tutorial with CurrentTerm singleton example
- Remove deprecated `___` separator mention (only `---` is supported)

Related to datajoint/datajoint-python#1341
Closes datajoint/datajoint-python#113

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Mark singleton tables as New in v2.1
f832270 
Add version-added admonitions to singleton table documentation:
- table-declaration.md reference spec
- university.ipynb tutorial (CurrentTerm example)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
fix: Make notebooks backend-agnostic (MySQL/PostgreSQL compatible)
6e5f8a6 
Changes for PostgreSQL compatibility:
- 04-queries.ipynb: Use CAST(correct AS INTEGER) for boolean aggregation
- allen-ccf.ipynb: Use single quotes for LIKE pattern strings
- languages.ipynb: Use single quotes for string comparisons
- university.ipynb: Use CASE WHEN for conditional aggregation
- sql-comparison.ipynb: Use single quotes for date string comparisons

Backend detection:
- json-type.ipynb: Skip on PostgreSQL (uses MySQL-specific JSON functions)
- All notebooks: Add DJ_BACKEND environment variable handling

Also adds PostgreSQL service to docker-compose.yaml.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Add environment variable configuration to all notebooks
6abdc0c 
All 21 documentation notebooks now support configuration via environment
variables (DJ_HOST, DJ_USER, DJ_PASS, DJ_PORT) for CI/testing purposes.

Also fixes:
- Remove broken pytest.skip in json-type.ipynb
- Revert CAST(correct AS INTEGER) to sum(correct) in 04-queries.ipynb
  (MySQL handles boolean sum natively)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Separate config from notebooks, add PostgreSQL compatibility
742a7a2 
Changes:
- Remove environment variable configuration from notebooks
  (DataJoint reads DJ_* env vars automatically)
- Add conftest.py to configure DataJoint for pytest runs
- Fix boolean aggregation in 04-queries.ipynb to work on both backends
  (use CASE WHEN instead of sum(boolean))
- Add PostgreSQL skip to json-type.ipynb (requires MySQL JSON functions)

Test results:
- MySQL: 21/21 passed
- PostgreSQL: 20/20 passed, 1 skipped (json-type)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Simplify JSON tutorial, add test outputs
784df1f 
- Simplified json-type.ipynb to focus on insert/fetch only
- Removed complex JSON path queries (not portable across backends)
- Added test output logs for MySQL and PostgreSQL runs

Test results:
- MySQL: 21/21 passed
- PostgreSQL: 21/21 passed

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko
docs: Update PostgreSQL test output (21/21 passed)
074281a
@dimitri-yatsenko @claude
docs: Re-execute notebooks with TLS disabled, add execution script
4c01f17 
- Re-run all notebooks against PostgreSQL with DJ_USE_TLS=false
- Removes SSL connection warning from notebook outputs
- Add scripts/execute-notebooks.sh for reproducible notebook execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko dimitri-yatsenko changed the base branch from pre/v2.0 to main January 23, 2026 04:57
dimitri-yatsenko and others added 6 commits January 23, 2026 08:57
@dimitri-yatsenko @claude
fix: PostgreSQL boolean aggregation in queries tutorial
0a58d44 
Change sum(correct) to sum(CASE WHEN correct THEN 1 ELSE 0 END)
PostgreSQL doesn't support summing booleans directly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
fix: PostgreSQL string quoting in sql-comparison tutorial
7bce685 
Use single quotes for string literals in SQL expressions.
PostgreSQL treats double quotes as identifiers.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Use decimal type for human-entered numeric fields
1a0174b 
- Change float32 to decimal for weight, duration, frame_rate
- Decimal is more appropriate for manually entered values
- Float remains for computed values and measurements

Affected tutorials:
- 01-first-pipeline: duration in Recording
- 03-data-entry: duration in Session
- 04-queries: weight in Subject, duration in Session
- 06-object-storage: frame_rate in ImagingSession

Also fixes:
- PostgreSQL boolean aggregation (sum(correct) -> CASE WHEN)
- PostgreSQL string quoting (double -> single quotes)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Use decimal for reaction_time, fix decimal-to-float conversions
e3376bd 
- Change reaction_time from float32 to decimal(3,2) in all tutorials
- Add explicit decimal-to-float conversion in computation code
- Decimal values from database need .astype(float) for numpy operations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
Merge pre/v2.1 into docs/singleton-tables
e166326 
Combines:
- Singleton tables documentation
- PostgreSQL compatibility fixes
- Decimal types for human-entered fields
- Secondary attributes terminology standardization
- Notebook execution script

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: Re-execute all notebooks after merge
0934958 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko dimitri-yatsenko mentioned this pull request Jan 23, 2026
Closed
3 tasks
MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 16:23

The merge-base changed after approval.

MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 16:37

The merge-base changed after approval.

dimitri-yatsenko and others added 2 commits January 23, 2026 10:48
@dimitri-yatsenko @claude
docs: add testing guide and replace Russian with Ukrainian
a9dc9d0 
- Add how-to/testing.md with pytest fixtures and CI/CD patterns
- Add Testing section to navigation in mkdocs.yaml
- Replace Russian language with Ukrainian in languages tutorial

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko @claude
docs: add testing guide to how-to index
3119156 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko dimitri-yatsenko mentioned this pull request Jan 23, 2026
Merged
@dimitri-yatsenko @claude
docs: use single quotes for strings in SQL restrictions
c427c8e 
PostgreSQL interprets double quotes as identifier references, not string
literals. Changed all examples to use the portable pattern:
  Table & "field = 'value'"

instead of the MySQL-only pattern:
  Table & 'field = "value"'

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@dimitri-yatsenko dimitri-yatsenko mentioned this pull request Jan 23, 2026
Merged
MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 17:50

The merge-base changed after approval.

MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 17:56

The merge-base changed after approval.

@MilagrosMarin MilagrosMarin self-requested a review January 23, 2026 17:59
MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 18:20

The merge-base changed after approval.

MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 18:31

The merge-base changed after approval.

MilagrosMarin
MilagrosMarin approved these changes Jan 23, 2026
View reviewed changes
Copy link
Collaborator

@MilagrosMarin MilagrosMarin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @dimitri-yatsenko. It seems we are facing some issues with merging. I am going to try again after adding this comment.

MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
@dimitri-yatsenko dimitri-yatsenko dismissed MilagrosMarin’s stale review January 23, 2026 18:36

The merge-base changed after approval.

MilagrosMarin
MilagrosMarin previously approved these changes Jan 23, 2026
View reviewed changes
Copy link
Collaborator

@MilagrosMarin MilagrosMarin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comprehensive documentation update with singleton tables, PostgreSQL compatibility, and terminology improvements. All CI checks pass. Approved.

@MilagrosMarin MilagrosMarin self-requested a review January 23, 2026 18:39
MilagrosMarin
MilagrosMarin approved these changes Jan 23, 2026
View reviewed changes
Copy link
Collaborator

@MilagrosMarin MilagrosMarin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-approving after branch update with latest main. CI checks pass. Comprehensive documentation update including singleton tables, PostgreSQL compatibility, decimal types for human-entered fields, and terminology standardization.

@MilagrosMarin MilagrosMarin merged commit 67fcc60 into main Jan 23, 2026
1 check passed
@dimitri-yatsenko dimitri-yatsenko deleted the docs/singleton-tables branch January 27, 2026 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@MilagrosMarin MilagrosMarin MilagrosMarin approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@dimitri-yatsenko @MilagrosMarin

Comments