From a617bc98109473bc077dcfe3fab38afc9769d583 Mon Sep 17 00:00:00 2001 From: MilagrosMarin Date: Thu, 22 Jan 2026 13:50:03 +0000 Subject: [PATCH 1/2] docs: Fix terminology inconsistencies and add missing nav entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix `is_external` → `is_store` parameter name in codec examples (8 instances) - Fix `path-addressed` → `schema-addressed` terminology (3 instances) - Add missing how-to guides to mkdocs.yaml navigation Co-Authored-By: Claude Opus 4.5 --- mkdocs.yaml | 3 +++ src/explanation/faq.md | 2 +- src/explanation/type-system.md | 2 +- src/how-to/define-tables.md | 2 +- src/how-to/use-object-storage.md | 2 +- src/reference/specs/type-system.md | 14 +++++++------- 6 files changed, 14 insertions(+), 11 deletions(-) diff --git a/mkdocs.yaml b/mkdocs.yaml index 4a157911..a3175789 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -52,6 +52,7 @@ nav: - how-to/index.md - Setup: - Installation: how-to/installation.md + - Manage Secrets: how-to/manage-secrets.md - Configure Database: how-to/configure-database.md - Configure Object Storage: how-to/configure-storage.md - Command-Line Interface: how-to/use-cli.md @@ -73,6 +74,8 @@ nav: - Handle Errors: how-to/handle-errors.md - Monitor Progress: how-to/monitor-progress.md - Object Storage: + - Overview: how-to/object-storage-overview.md + - Choose Storage Type: how-to/choose-storage-type.md - Use Object Storage: how-to/use-object-storage.md - Use NPY Codec: how-to/use-npy-codec.md - Use Plugin Codecs: how-to/use-plugin-codecs.md diff --git a/src/explanation/faq.md b/src/explanation/faq.md index c9a7e228..b34904fc 100644 --- a/src/explanation/faq.md +++ b/src/explanation/faq.md @@ -88,7 +88,7 @@ Object-Relational Mappers treat large objects as opaque binary blobs or leave fi - Relational semantics apply: referential integrity, cascading deletes, query filtering - Multiple access patterns: lazy `ObjectRef`, streaming via fsspec, explicit download -- Two addressing modes: path-addressed (by primary key) and hash-addressed (deduplicated) +- Two addressing modes: schema-addressed (by primary key) and hash-addressed (deduplicated) The object store is part of the relational model — queryable and integrity-protected like any other attribute. diff --git a/src/explanation/type-system.md b/src/explanation/type-system.md index bfd3e6db..892b49f9 100644 --- a/src/explanation/type-system.md +++ b/src/explanation/type-system.md @@ -315,7 +315,7 @@ class GraphCodec(dj.Codec): """Store NetworkX graphs.""" name = "graph" - def get_dtype(self, is_external): + def get_dtype(self, is_store): return "" def encode(self, graph, *, key=None, store_name=None): diff --git a/src/how-to/define-tables.md b/src/how-to/define-tables.md index 3566262e..7e29cd72 100644 --- a/src/how-to/define-tables.md +++ b/src/how-to/define-tables.md @@ -160,7 +160,7 @@ Codecs serialize Python objects to database storage. Use angle brackets for code | `` | Serialized objects in object storage | | `` | File attachments in database | | `` | File attachments in object storage | -| `` | Files/folders via ObjectRef (path-addressed, supports Zarr/HDF5) | +| `` | Files/folders via ObjectRef (schema-addressed, supports Zarr/HDF5) | Example: diff --git a/src/how-to/use-object-storage.md b/src/how-to/use-object-storage.md index 154703ce..f4a4e531 100644 --- a/src/how-to/use-object-storage.md +++ b/src/how-to/use-object-storage.md @@ -149,7 +149,7 @@ class Dataset(dj.Manual): """ ``` -Use path-addressed storage for: +Use schema-addressed storage for: - Zarr arrays (chunked, appendable) - HDF5 files diff --git a/src/reference/specs/type-system.md b/src/reference/specs/type-system.md index 5edfde66..03920382 100644 --- a/src/reference/specs/type-system.md +++ b/src/reference/specs/type-system.md @@ -410,8 +410,8 @@ class FilepathCodec(dj.Codec): """Store-relative file references. External only.""" name = "filepath" - def get_dtype(self, is_external: bool) -> str: - if not is_external: + def get_dtype(self, is_store: bool) -> str: + if not is_store: raise DataJointError(" requires @store") return "json" @@ -512,8 +512,8 @@ class BlobCodec(dj.Codec): """Serialized Python objects. Supports internal and external.""" name = "blob" - def get_dtype(self, is_external: bool) -> str: - return "" if is_external else "bytes" + def get_dtype(self, is_store: bool) -> str: + return "" if is_store else "bytes" def encode(self, value, *, key=None, store_name=None) -> bytes: from . import blob @@ -551,8 +551,8 @@ class AttachCodec(dj.Codec): """File attachment with filename. Supports in-table and in-store.""" name = "attach" - def get_dtype(self, is_external: bool) -> str: - return "" if is_external else "bytes" + def get_dtype(self, is_store: bool) -> str: + return "" if is_store else "bytes" def encode(self, filepath, *, key=None, store_name=None) -> bytes: path = Path(filepath) @@ -662,7 +662,7 @@ def garbage_collect(store_name): 2. **Core types are scientist-friendly**: `float32`, `int8`, `bool`, `bytes` instead of `FLOAT`, `TINYINT`, `LONGBLOB` 3. **Codecs use angle brackets**: ``, ``, `` - distinguishes from core types 4. **`@` indicates in-store storage**: No `@` = database, `@` present = object store -5. **`get_dtype(is_external)` method**: Codecs resolve dtype at declaration time based on storage mode +5. **`get_dtype(is_store)` method**: Codecs resolve dtype at declaration time based on storage mode 6. **Codecs are composable**: `` uses ``, which uses `json` 7. **Built-in in-store codecs use JSON dtype**: Stores metadata (path, hash, store name, etc.) 8. **Two OAS regions**: object (PK-addressed) and hash (hash-addressed) within managed stores From dcb12f80c4ac3627f558f128401140678f1a0c04 Mon Sep 17 00:00:00 2001 From: MilagrosMarin Date: Thu, 22 Jan 2026 15:58:26 +0000 Subject: [PATCH 2/2] fix: Remove nav entries for non-existent files Per reviewer feedback, removing mkdocs.yaml nav entries for files that don't exist yet: - how-to/manage-secrets.md - how-to/object-storage-overview.md - how-to/choose-storage-type.md These can be added in a future PR when the content is created. Co-Authored-By: Claude Opus 4.5 --- mkdocs.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/mkdocs.yaml b/mkdocs.yaml index a3175789..4a157911 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -52,7 +52,6 @@ nav: - how-to/index.md - Setup: - Installation: how-to/installation.md - - Manage Secrets: how-to/manage-secrets.md - Configure Database: how-to/configure-database.md - Configure Object Storage: how-to/configure-storage.md - Command-Line Interface: how-to/use-cli.md @@ -74,8 +73,6 @@ nav: - Handle Errors: how-to/handle-errors.md - Monitor Progress: how-to/monitor-progress.md - Object Storage: - - Overview: how-to/object-storage-overview.md - - Choose Storage Type: how-to/choose-storage-type.md - Use Object Storage: how-to/use-object-storage.md - Use NPY Codec: how-to/use-npy-codec.md - Use Plugin Codecs: how-to/use-plugin-codecs.md