Conversation
ghost
self-assigned this
Deploying docs-source-network with
|
| Latest commit: |
e637324
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3f964d5e.docs-source-network.pages.dev |
| Branch Preview URL: | https://revamp-time-travelling.docs-source-network.pages.dev |
There was a problem hiding this comment.
- https://github.com/sourcenetwork/defradb/blob/develop/tests/integration/query/simple/with_version_test.go
- https://github.com/sourcenetwork/defradb/blob/develop/tests/integration/query/simple/with_version_order_test.go
- https://github.com/sourcenetwork/defradb/blob/develop/tests/integration/query/simple/with_version_cid_test.go
- https://github.com/sourcenetwork/defradb/blob/develop/tests/integration/query/simple/with_version_cid_doc_ids_test.go
|
|
||
| :::caution | ||
| **GAP: Critical information missing.** The current documentation does not explain how developers obtain the CID values needed for time travelling queries. This section needs to cover: | ||
| 1. How to query a document's commit history to see available CIDs |
There was a problem hiding this comment.
📝 WalkthroughWalkthroughThis PR reorganizes time travelling queries documentation by replacing a single how-to guide with a two-file structure: a conceptual overview in the Concepts folder and a revised how-to guide. The old guide is removed and its content distributed across the new files with expanded coverage. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@docs/defradb/Concepts/time-travel.md`:
- Around line 47-52: The fenced code blocks in the time-travel doc are missing
language identifiers and will trigger MD040; update each triple-backtick block
shown (the ASCII diagram block "[Genesis] → [Update 1] …", the JSON example '{
"name": "Alicia" }', and the ASCII steps "Step 1: Trace backward …") to include
a language token (e.g., ```text for ASCII diagrams and ```json for the JSON
object) so the linter is satisfied; apply the same change to the other
occurrences noted (lines 80-82 and 92-98 equivalents) by adding the appropriate
language after the opening ``` for each block.
- Line 143: Update the broken related-resource link in the docs by replacing the
target filename "time-travelling-queries-how-to.md" with the correct
"time-travel-how-to.md" for the link labeled "**[How to Use Time Travelling
Queries]**" in time-travel.md so that the link points to the existing
time-travel-how-to.md document.
In `@docs/defradb/How-to` Guides/time-travel-how-to.md:
- Around line 62-81: The docs contain GAP placeholders under the "Finding a
Document's CIDs" section and the examples note; replace those with concrete
content: add a visual update-graph diagram and an explanatory caption, include
example response payloads for time-travel queries and an example demonstrating
querying multiple versions by CID (refer to the "Finding a Document's CIDs" and
the earlier examples note), and add a CID-discovery subsection that shows how to
list a document's commit history, whether CIDs appear in mutation responses, and
concrete example queries/commands for retrieving versions (reference the
commit-history query and mutation response examples in the guide to ensure names
match). Ensure each new example includes the query/command text and the expected
response payloads so readers can reproduce the steps.
- Line 97: Update the broken "Concepts" link in time-travel-how-to.md: replace
the current link target "time-travelling-queries-concepts.md" with the correct
path "docs/defradb/Concepts/time-travel.md" so the Review line ("Review [Time
Travelling Queries: Concepts](...)") points to the existing Concepts file.
- Around line 12-16: The doc incorrectly calls CIDs "32-bit hexadecimal version
identifiers"; update the text in the time-travel guide to say DefraDB accepts
standard multiformats CIDs (the same as IPFS/IPLD) — self-describing identifiers
composed of multibase, version, multicodec and multihash — and note the common
base32 string form (e.g., "bafy...") rather than hex. Replace the sentence that
begins "Add a `cid` parameter to your query with the 32-bit hexadecimal version
identifier" with one that instructs users to pass a multiformat CID string, and
optionally include a short example CID and a pointer that DefraDB expects the
standard CID representation.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/defradb/Concepts/time-travel-query-diagram.svgis excluded by!**/*.svg
📒 Files selected for processing (3)
docs/defradb/Concepts/time-travel.mddocs/defradb/How-to Guides/time-travel-how-to.mddocs/defradb/How-to Guides/time-traveling-queries.md
💤 Files with no reviewable changes (1)
- docs/defradb/How-to Guides/time-traveling-queries.md
🧰 Additional context used
🪛 LanguageTool
docs/defradb/How-to Guides/time-travel-how-to.md
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...(Content Identifier) of the version you want to retrieve ## Run a Regular Query A sta...
(REP_WANT_TO_VB)
docs/defradb/Concepts/time-travel.md
[style] ~69-~69: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...le references**: A CID always points to exactly the same data Example CID: `bafybeieqnthjlvr64a...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
[style] ~116-~116: This phrase is redundant. Consider writing “point” or “time”.
Context: ... include related documents at that same point in time. Example scenario: You have `Book...
(MOMENT_IN_TIME)
🪛 markdownlint-cli2 (0.18.1)
docs/defradb/Concepts/time-travel.md
47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cloudflare Pages
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| ``` | ||
| [Genesis] → [Update 1] → [Update 2] → [Update 3] → [Current State] | ||
| ↑ | ||
| First Most recent | ||
| commit commit | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
These blocks will fail MD040. Add a language like text (or none) to silence the linter.
🔧 Suggested fix
-```
+```text
[Genesis] → [Update 1] → [Update 2] → [Update 3] → [Current State]
↑
First Most recent
commit commit
-```
+```
-```
+```json
{ "name": "Alicia" }
-```
+```
-```
+```text
Step 1: Trace backward Step 2: Replay forward
[Target] ← [Update] ← [Genesis] [Genesis] → [Update] → [Target] ✓
↓
Return result
-```
+```Also applies to: 80-82, 92-98
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/defradb/Concepts/time-travel.md` around lines 47 - 52, The fenced code
blocks in the time-travel doc are missing language identifiers and will trigger
MD040; update each triple-backtick block shown (the ASCII diagram block
"[Genesis] → [Update 1] …", the JSON example '{ "name": "Alicia" }', and the
ASCII steps "Step 1: Trace backward …") to include a language token (e.g.,
```text for ASCII diagrams and ```json for the JSON object) so the linter is
satisfied; apply the same change to the other occurrences noted (lines 80-82 and
92-98 equivalents) by adding the appropriate language after the opening ``` for
each block.
|
|
||
| ## Related Resources | ||
|
|
||
| - **[How to Use Time Travelling Queries](time-travelling-queries-how-to.md)** — Step-by-step instructions with examples |
There was a problem hiding this comment.
Fix broken related-resource link.
The target file appears to be time-travel-how-to.md, not time-travelling-queries-how-to.md.
🔧 Suggested fix
-- **[How to Use Time Travelling Queries](time-travelling-queries-how-to.md)** — Step-by-step instructions with examples
+- **[How to Use Time Travelling Queries](../How-to Guides/time-travel-how-to.md)** — Step-by-step instructions with examples📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **[How to Use Time Travelling Queries](time-travelling-queries-how-to.md)** — Step-by-step instructions with examples | |
| - **[How to Use Time Travelling Queries](../How-to Guides/time-travel-how-to.md)** — Step-by-step instructions with examples |
🤖 Prompt for AI Agents
In `@docs/defradb/Concepts/time-travel.md` at line 143, Update the broken
related-resource link in the docs by replacing the target filename
"time-travelling-queries-how-to.md" with the correct "time-travel-how-to.md" for
the link labeled "**[How to Use Time Travelling Queries]**" in time-travel.md so
that the link points to the existing time-travel-how-to.md document.
| Time Traveling Queries let you query documents at any previous state by specifying a commit's Content Identifier (CID). Unlike traditional databases that overwrite data, DefraDB preserves every update in an immutable update graph. | ||
|
|
||
| **How to use:** Add a `cid` parameter to your query with the 32-bit hexadecimal version identifier. Works with minimal changes to regular queries – same syntax, just add the CID. | ||
|
|
||
| **Key mechanism:** Every document update is stored as a delta payload in a Merkle CRDT update graph. Queries traverse from the target state back to genesis, then replay operations forward to reconstruct the historical state. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
DefraDB CID format content identifier specification
💡 Result:
DefraDB uses standard multiformats CIDs (the same CID format used by IPFS/IPLD): self‑describing content identifiers composed of multibase (optional string encoding), a CID version (v1 typical), a multicodec for the content type, and a multihash (hash function + digest). In DefraDB docs and client examples commits are identified by CIDs (e.g. bafy... strings) and you should follow the CID / multiformats specification (CIDv1, multibase, multicodec, multihash) when creating or parsing them. [1][2][3]
Sources:
- DefraDB docs / examples showing commits identified by cid. [1]
- multiformats CID specification (CIDv1 structure: multibase, multicodec, multihash). [2]
- IPFS docs (practical notes on CID v0/v1 and base encodings). [3]
🌐 Web query:
IPLD CID format encoding base32 base16 multibase specification
💡 Result:
Short summary:
-
CID structure (raw bytes): . As a string it is prefixed with a Multibase code: . CIDv1 is multibase-capable; CIDv0 is the legacy base58btc form. [1][3]
-
Multibase: a single-character prefix that self-identifies the base encoding used for the bytes that follow. Common codes:
- 'b' = base32 (RFC 4648, lowercase, no padding) — the recommended/default textual encoding for CIDv1 (DNS-safe).
- 'f' = base16 (hex, lowercase).
- 'z' = base58btc (used by CIDv0 strings).
(Multibase includes many other encodings; see registry for full list and codes.) [1][4]
-
Practical notes:
- To convert CIDv0 → CIDv1 (so you can represent it as base32/base16/etc.) use ipfs cid format or multiformats libraries. [3]
- Multibase implementations/registries (JS/Go/Python) follow the Multiformats Multibase spec and expose named encodings like base32/base16. [2][4]
Key references:
- Multibase spec & registry (multiformats/multibase). [1]
- Multiformats documentation (multibase API examples). [2]
- IPFS docs: Content Identifiers (CIDs) and recommendation to use base32 for CIDv1. [3]
- Go multibase constants (shows codes like 'b' and 'f'). [4]
If you want, I can: show examples converting a specific CID to base32/base16, or give code snippets (JS/Go/Python).
Correct CID format description.
CIDs are not "32‑bit hexadecimal version identifiers." DefraDB uses standard multiformats CIDs (the same format as IPFS/IPLD), which are self-describing identifiers combining multibase encoding, version, multicodec, and multihash. The typical string representation uses base32 encoding (e.g., bafy... strings), not hex. The documentation should describe CIDs accurately to avoid misleading users about their structure.
🔧 Suggested fix
-**How to use:** Add a `cid` parameter to your query with the 32-bit hexadecimal version identifier. Works with minimal changes to regular queries – same syntax, just add the CID.
+**How to use:** Add a `cid` parameter to your query with the Content Identifier (CID) for the version you want to query. Works with minimal changes to regular queries – same syntax, just add the CID.🤖 Prompt for AI Agents
In `@docs/defradb/How-to` Guides/time-travel-how-to.md around lines 12 - 16, The
doc incorrectly calls CIDs "32-bit hexadecimal version identifiers"; update the
text in the time-travel guide to say DefraDB accepts standard multiformats CIDs
(the same as IPFS/IPLD) — self-describing identifiers composed of multibase,
version, multicodec and multihash — and note the common base32 string form
(e.g., "bafy...") rather than hex. Replace the sentence that begins "Add a `cid`
parameter to your query with the 32-bit hexadecimal version identifier" with one
that instructs users to pass a multiformat CID string, and optionally include a
short example CID and a pointer that DefraDB expects the standard CID
representation.
| :::note | ||
|
|
||
| **GAP: Additional examples needed.** This section should include: | ||
|
|
||
| 1. A visual diagram showing the document's update graph and how the query relates to it | ||
| 2. Example response payloads showing what the returned data looks like | ||
| 3. An example showing multiple versions of the same document being queried at different CIDs | ||
|
|
||
| ::: | ||
|
|
||
| ## Finding a Document's CIDs | ||
|
|
||
| :::caution | ||
| **GAP: Critical information missing.** The current documentation does not explain how developers obtain the CID values needed for time travelling queries. This section needs to cover: | ||
|
|
||
| 1. How to query a document's commit history to see available CIDs | ||
| 2. Whether CIDs are returned in mutation responses when creating/updating documents | ||
| 3. Example queries or commands for listing available versions | ||
|
|
||
| ::: |
There was a problem hiding this comment.
Resolve GAP sections before release.
These sections explicitly state critical missing content (CID discovery, examples, diagrams). Shipping with placeholders makes the guide incomplete and blocks user success.
If you want, I can draft the missing examples and CID retrieval steps and open a tracking issue.
🤖 Prompt for AI Agents
In `@docs/defradb/How-to` Guides/time-travel-how-to.md around lines 62 - 81, The
docs contain GAP placeholders under the "Finding a Document's CIDs" section and
the examples note; replace those with concrete content: add a visual
update-graph diagram and an explanatory caption, include example response
payloads for time-travel queries and an example demonstrating querying multiple
versions by CID (refer to the "Finding a Document's CIDs" and the earlier
examples note), and add a CID-discovery subsection that shows how to list a
document's commit history, whether CIDs appear in mutation responses, and
concrete example queries/commands for retrieving versions (reference the
commit-history query and mutation response examples in the guide to ensure names
match). Ensure each new example includes the query/command text and the expected
response payloads so readers can reproduce the steps.
|
|
||
| ## Next Steps | ||
|
|
||
| - Review [Time Travelling Queries: Concepts](time-travelling-queries-concepts.md) to understand how the update graph and delta payloads work |
There was a problem hiding this comment.
Fix broken “Concepts” link.
The target file is docs/defradb/Concepts/time-travel.md, not time-travelling-queries-concepts.md.
🔧 Suggested fix
-- Review [Time Travelling Queries: Concepts](time-travelling-queries-concepts.md) to understand how the update graph and delta payloads work
+- Review [Time Travelling Queries: Concepts](../Concepts/time-travel.md) to understand how the update graph and delta payloads work📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Review [Time Travelling Queries: Concepts](time-travelling-queries-concepts.md) to understand how the update graph and delta payloads work | |
| - Review [Time Travelling Queries: Concepts](../Concepts/time-travel.md) to understand how the update graph and delta payloads work |
🤖 Prompt for AI Agents
In `@docs/defradb/How-to` Guides/time-travel-how-to.md at line 97, Update the
broken "Concepts" link in time-travel-how-to.md: replace the current link target
"time-travelling-queries-concepts.md" with the correct path
"docs/defradb/Concepts/time-travel.md" so the Review line ("Review [Time
Travelling Queries: Concepts](...)") points to the existing Concepts file.
2 participants
Summary by CodeRabbit
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.