Restructure documentation using Diataxis framework#379
Conversation
7647e30 to
b8d76a5
Compare
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly overhauls the ArcadeDB documentation by adopting the Diataxis framework, which categorizes content into Tutorials, How-To Guides, Explanations (Concepts), and Reference. This strategic reorganization aims to enhance the user experience by making information more accessible and relevant to different user needs, from quickstarts for new developers to detailed API references for experienced users. The change improves the overall structure and navigability of the documentation, ensuring that users can efficiently find the information they need to learn, use, and operate ArcadeDB. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
The code review identified several issues. The variable name 'for' in java-select-api.adoc is a reserved keyword in Java and should be renamed. The btoa() function in http-nodejs.adoc is a browser-specific API and should be replaced with the Buffer class for Node.js compatibility. The term "extendable hashing" in concepts/indexes.adoc and java-schema.adoc is a typo and should be corrected to "extendible hashing". There's an inconsistency in the syntax for defining vector properties in how-to/data-modeling/vector-embeddings.adoc, where ARRAY_OF_FLOATS should be changed to LIST OF FLOAT for consistency. There is a typo in the comment in cypher-clauses.adoc, where // Multiple UNIONs should be // Multiple UNIONNs.
Note: Security Review did not run due to the size of the PR.
|
|
||
| // Multi-hop: friends of friends | ||
| Set<String> fof = database.select().fromType("User") | ||
| Set<String> for = database.select().fromType("User") |
There was a problem hiding this comment.
| [source,javascript] | ||
| ---- | ||
| const base = 'http://localhost:2480/api/v1'; | ||
| const auth = 'Basic ' + btoa('root:arcadedb'); |
There was a problem hiding this comment.
The btoa() function is not available in Node.js by default; it is a browser-specific API. For server-side Node.js code, you should use the Buffer class to perform Base64 encoding. This will make the code example runnable in a Node.js environment.
const auth = 'Basic ' + Buffer.from('root:arcadedb').toString('base64');This same issue is present on line 97.
const auth = 'Basic ' + Buffer.from('root:arcadedb').toString('base64');
|
|
||
| - **<<lsm-tree,LSM Tree>>** (default) — Optimized for range scans, ordered iteration, and write-heavy workloads. | ||
| - **Hash Index** — O(1) equality lookups using https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing]. Best for primary key access, JOINs, and edge traversal where ordering is not needed. | ||
| - **Hash Index** — O(1) equality lookups using https://en.wikipedia.org/wiki/Extendible_hashing[extendable hashing]. Best for primary key access, JOINs, and edge traversal where ordering is not needed. |
There was a problem hiding this comment.
The term for the hashing algorithm is "Extendible Hashing". The change to "extendable" is a typo. Please revert it to "extendible" to maintain technical accuracy. The linked Wikipedia article also uses "Extendible".
- **Hash Index** — O(1) equality lookups using https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing]. Best for primary key access, JOINs, and edge traversal where ordering is not needed.
| ==== Hash Index algorithm | ||
|
|
||
| ArcadeDB's Hash Index uses https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing], a disk-oriented algorithm that provides O(1) equality lookups with typically 1-2 page reads. | ||
| ArcadeDB's Hash Index uses https://en.wikipedia.org/wiki/Extendible_hashing[extendable hashing], a disk-oriented algorithm that provides O(1) equality lookups with typically 1-2 page reads. |
There was a problem hiding this comment.
The term for the hashing algorithm is "Extendible Hashing". The change to "extendable" is a typo. Please revert it to "extendible" to maintain technical accuracy.
ArcadeDB's Hash Index uses https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing], a disk-oriented algorithm that provides O(1) equality lookups with typically 1-2 page reads.
| CREATE PROPERTY Product.imageEmbedding ARRAY_OF_FLOATS | ||
| CREATE PROPERTY Product.textEmbedding ARRAY_OF_FLOATS |
There was a problem hiding this comment.
There's an inconsistency in the syntax for defining vector properties. This file uses ARRAY_OF_FLOATS, while other parts of the documentation use LIST OF FLOAT (e.g., line 32 in this file) or ARRAY OF FLOATS. For consistency and clarity, it would be best to use a single, correct syntax throughout. I'd suggest using LIST OF FLOAT as it appears in the more basic examples.
CREATE PROPERTY Product.imageEmbedding LIST OF FLOAT
CREATE PROPERTY Product.textEmbedding LIST OF FLOAT
| MATCH (c:Company) RETURN c.name AS name | ||
|
|
||
| // Multiple UNIONs | ||
| // Multiple UNIONNs |
| * `indexType` can be: | ||
| ** `LSM_TREE`, implemented as a https://en.wikipedia.org/wiki/Log-structured_merge-tree[Log Structured Merge tree]. Best for range scans and ordered iteration. | ||
| ** `HASH`, implemented using https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing]. Provides O(1) equality lookups — best for primary keys, JOINs, and edge traversal where ordering is not needed. Does not support range queries. | ||
| ** `HASH`, implemented using https://en.wikipedia.org/wiki/Extendible_hashing[extendable hashing]. Provides O(1) equality lookups — best for primary keys, JOINs, and edge traversal where ordering is not needed. Does not support range queries. |
There was a problem hiding this comment.
The term for the hashing algorithm is "Extendible Hashing". The change to "extendable" is a typo. Please revert it to "extendible" to maintain technical accuracy.
** `HASH`, implemented using https://en.wikipedia.org/wiki/Extendible_hashing[extendible hashing]. Provides O(1) equality lookups — best for primary keys, JOINs, and edge traversal where ordering is not needed. Does not support range queries.
| ---- | ||
|
|
||
| NOTE: Hash indexes use <<hash-index,extendible hashing>> and provide O(1) equality lookups — significantly faster than LSM Tree for point queries (`WHERE key = value`). However, they do not support range scans (`<`, `>`, `BETWEEN`) or ordered iteration (`ORDER BY`). Use `UNIQUE`/`NOTUNIQUE` (LSM Tree) when you need range queries or ordering. | ||
| NOTE: Hash indexes use <<hash-index,extendable hashing>> and provide O(1) equality lookups — significantly faster than LSM Tree for point queries (`WHERE key = value`). However, they do not support range scans (`<`, `>`, `BETWEEN`) or ordered iteration (`ORDER BY`). Use `UNIQUE`/`NOTUNIQUE` (LSM Tree) when you need range queries or ordering. |
There was a problem hiding this comment.
The term for the hashing algorithm is "Extendible Hashing". The change to "extendable" is a typo. Please revert it to "extendible" to maintain technical accuracy.
NOTE: Hash indexes use <<hash-index,extendible hashing>> and provide O(1) equality lookups — significantly faster than LSM Tree for point queries (`WHERE key = value`). However, they do not support range scans (`<`, `>`, `BETWEEN`) or ordered iteration (`ORDER BY`). Use `UNIQUE`/`NOTUNIQUE` (LSM Tree) when you need range queries or ordering.
🧪 CI InsightsHere's what we observed from your CI run for f41d7b7. 🟢 All jobs passed!But CI Insights is watching 👀 |
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update relative image paths from ../images/ to ../../images/ for files that moved from depth 1 to depth 2 in the new directory structure. Update all GitHub edit links to point to the new file locations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Each page documents a complete use case from the arcadedb-usecases repo with architecture overview, key queries, and try-it-yourself instructions: recommendation-engine, knowledge-graph, graph-rag, fraud-detection, realtime-analytics, social-network-analytics, supply-chain, iam, customer-360. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Stub pages for semantic-search, geospatial-analytics, content-management, network-monitoring, and data-lineage with planned features and target scenarios. Replaces plain-text list in chapter.adoc with included pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Python tutorial uses psycopg via PostgreSQL protocol (sourced from IAM use case patterns). JavaScript tutorial uses pg client via PostgreSQL protocol (sourced from supply-chain use case patterns). Both cover schema creation, SQL/Cypher queries, and vector search. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Python guide now covers PostgreSQL protocol (psycopg), HTTP/JSON API (requests), and embedded bindings with code examples. JavaScript guide now covers PostgreSQL protocol (pg), HTTP/JSON API (fetch + axios), and TypeScript usage with code examples. Both recommend PostgreSQL protocol as the primary approach. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… how-to) Phase 3 - Vector & AI/ML documentation: - concepts/vector-search.adoc: Architecture, HNSW/DiskANN, quantization, similarity functions, parameter tuning guide - tutorials/vector-search-tutorial.adoc: Step-by-step from schema to hybrid vector+graph queries - how-to/data-modeling/vector-embeddings.adoc: Embedding model selection, index creation, quantization trade-offs, hybrid search, batch ingestion - reference/vector-functions/: Categorized index of 40+ vector SQL functions (distance, manipulation, quantization, scoring, sparse) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…refs Move 68 graph algorithms (5131 lines) from appendix to reference/ graph-algorithms/ with a chapter overview linking to all categories. Appendix now contains a redirect. Add algorithm cross-references to fraud-detection, social-network-analytics, and iam use cases. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…uning Phase 5 - Time Series, gRPC, Monitoring: - tutorials/time-series-tutorial.adoc: 10-step tutorial from schema creation through PromQL and continuous aggregates - reference/time-series/chapter.adoc: Quick reference linking to the comprehensive timeseries concepts page - reference/grpc-api/: 3 files documenting 2 services, 22 RPCs, message types, enums, and Python/Node.js connection examples - how-to/operations/monitoring.adoc: Prometheus integration, metrics, Grafana dashboard setup - how-to/operations/performance-tuning.adoc: Memory, indexes, EXPLAIN, buckets, page size, connection pools Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add concepts/multi-model.adoc explaining ArcadeDB's unified multi-model architecture and concepts/high-availability.adoc covering the leader-replica replication model. Add See Also cross-reference sections to graphs.adoc and timeseries.adoc linking to related use cases and tutorials. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
SQL and Cypher used level-2 headings (== ) making them top-level sections instead of subsections under Reference. Connectivity, Operations, Data Modeling, and Migration children used the same heading level as their parents, appearing as siblings instead of nested children. Bumped all heading levels so the hierarchy renders correctly: - Reference (==) > SQL, Cypher, Gremlin, etc. (===) - How-To (==) > Connectivity (===) > JDBC, Postgres, etc. (====) - How-To (==) > Operations (===) > Server, Backup, etc. (====) - How-To (==) > Data Modeling (===) > Full-Text, Geospatial, etc. (====) - How-To (==) > Migration (===) > Importer (====) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Create a centralized stylesheet matching the arcadedb.com website design language. Replaces Asciidoctor defaults with Inter/Space Grotesk/JetBrains Mono fonts, website color palette, dark code blocks with remapped Rouge syntax highlighting, styled TOC sidebar, tables, and admonition blocks. Consolidates inline CSS from index.adoc, content.adoc, and web-footer.adoc. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rename the tutorial anchor from [[multi-model]] to [[multi-model-tutorial]] to avoid conflict with the concepts page anchor. Update cross-references in content.adoc accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…bles - Rename 5 duplicate anchor IDs (sql-insert, agg-median, map-submap, monitoring, high-availability) to unique names, update cross-references - Fix section heading levels in 5 files (concepts/high-availability, concepts/graphs, cypher-compatibility, studio/server, studio/database) - Switch 10 D2 diagrams from sketch:true to sketch:false to eliminate SVG <pattern> tag warnings in PDF generation - Fix incomplete table rows in java-ref-database and algorithms - Fix explicit list numbering in java-vectors to use auto-numbering Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…concepts - Add Diataxis navigation TOC (Tutorials, How-Tos, Explanations, Reference) - Group reference into Query Languages and APIs sub-sections via leveloffset - Move Data Types and Binary Types to top of reference section - Make Binary Types a sub-section of Data Types - Rename Concepts to Explanations per Diataxis terminology - Move Storage Internals and LSM-Tree from Reference to Explanations - Integrate "Features Used" bullet lists into use-case intro paragraphs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4b4fe89 to
ffae66d
Compare
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Summary
Restructures the ArcadeDB documentation from 10 flat sections into a Diataxis-based taxonomy for improved findability and broader audience reach (Python, JavaScript, AI/ML developers).
New structure
Key changes
Validation
docs-validator.py: all filenames, anchors, and cross-references validmvn generate-resources: BUILD SUCCESS (HTML + PDF)Test plan
python3 docs-validator.py— all checks passmvn generate-resources— BUILD SUCCESSmvn jetty:runand verify navigation at http://localhost:8080🤖 Generated with Claude Code