Add dev docs for Neo4j by BeArchiTek · Pull Request #8501 · opsmill/infrahub

BeArchiTek · 2026-02-27T13:34:00Z

(Following feature MVP in #8448)

Document lessons learned from the enhanced search feature, where missing value_lower on AttributeValueIndexed caused silent data integrity issues.

Add value_lower property and write path registry to database-schema.md
Add Neo4j gotchas section (NOT NULL, MERGE semantics, index bypass)
Add MERGE vs CREATE semantics to query-pattern.md
New guide: writing-migrations.md (IN TRANSACTIONS, idempotency)
New guide: adding-node-properties.md (checklist for new properties)
Update backend AGENTS.md with references to new guides

Summary by CodeRabbit

Documentation
- Added comprehensive guides for backend developers on writing safe Neo4j graph migrations and on adding properties to existing nodes, including step-by-step checklists and migration best practices.
- Expanded database schema docs with a new derived-property (case-insensitive search) recommendation, property constraint gotchas, indexing guidance, and consolidated write-path considerations.
- Added detailed guidance on MERGE vs CREATE semantics and recommended query patterns.

…umentation Document lessons learned from the enhanced search feature where missing value_lower on AttributeValueIndexed caused silent data integrity issues. - Add value_lower property and write path registry to database-schema.md - Add Neo4j gotchas section (NOT NULL, MERGE semantics, index bypass) - Add MERGE vs CREATE semantics to query-pattern.md - New guide: writing-migrations.md (IN TRANSACTIONS, idempotency) - New guide: adding-node-properties.md (checklist for new properties) - Update backend AGENTS.md with references to new guides Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

coderabbitai · 2026-02-27T13:34:29Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 39e2c03 and 550bb14.

📒 Files selected for processing (1)

dev/knowledge/backend/database-schema.md

Walkthrough

This pull request adds comprehensive backend documentation covering Neo4j database operations. Two new guide documents are introduced: one describing the process for writing graph migrations and another detailing steps for adding new properties to existing Neo4j nodes. The knowledge base is expanded with additional details on the database schema, including a new value_lower property, write paths for AttributeValueIndexed nodes, and Neo4j property constraints. A section comparing MERGE vs CREATE semantics in Cypher is added to the query pattern documentation. All changes are documentation-focused with no modifications to functional code or public APIs.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add dev docs for Neo4j' accurately describes the main change: adding multiple documentation files for Neo4j backend development.
Description check	✅ Passed	The description covers Why (problem context from `#8448`), What changed (six bullet points documenting all additions), and follows the template appropriately for a documentation PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

dev/guides/backend/adding-node-properties.md (1)

24-32: Use repo-root file paths consistently in the write-path table.

At Line 26-Line 32, shortened paths (core/...) are inconsistent with Step 1 commands (backend/infrahub/...) and can mislead copy/paste navigation.

Proposed doc-only path normalization

-| `BaseAttribute.to_db()` | `core/attribute.py` | Normal CRUD (create/update node attributes) |
-| `NodeCreateFullBatchQuery` | `core/query/node.py` | Batch node creation |
-| `Resource pool allocation` | `core/query/resource_manager.py` |
-| `Graph migrations` | `core/migrations/graph/m0*.py` |
-| `Schema migrations` | `core/migrations/schema/*.py` |
-| `Shared migration queries` | `core/migrations/query/*.py` |
+| `BaseAttribute.to_db()` | `backend/infrahub/core/attribute.py` | Normal CRUD (create/update node attributes) |
+| `NodeCreateFullBatchQuery` | `backend/infrahub/core/query/node.py` | Batch node creation |
+| `Resource pool allocation` | `backend/infrahub/core/query/resource_manager.py` |
+| `Graph migrations` | `backend/infrahub/core/migrations/graph/m0*.py` |
+| `Schema migrations` | `backend/infrahub/core/migrations/schema/*.py` |
+| `Shared migration queries` | `backend/infrahub/core/migrations/query/*.py` |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@dev/guides/backend/adding-node-properties.md` around lines 24 - 32, The table
uses shortened paths like `core/attribute.py → to_db()` and `core/query/node.py
→ NodeCreateFullBatchQuery`, which is inconsistent with Step 1's repo-root style
(e.g., `backend/infrahub/...`); update each entry in the write-path table to the
full repo-root paths matching the commands in Step 1 (for example replace
`core/attribute.py` with the full path under `backend/infrahub/...` and
similarly expand `core/query/resource_manager.py`,
`core/migrations/graph/m0*.py`, `core/migrations/schema/*.py`, and
`core/migrations/query/*.py`) so copy/paste navigation is accurate and
consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@dev/knowledge/backend/database-schema.md`:
- Around line 409-410: Replace the asymptotic claim "O(1)-ish" near the WHERE
example that uses the TEXT index on value_lower; instead update the sentence to
say the condition is "index-backed and avoids full scans" (or similar
non-asymptotic phrasing) so the doc accurately reflects Neo4j query planning for
the WHERE av.value_lower CONTAINS $search example.

---

Nitpick comments:
In `@dev/guides/backend/adding-node-properties.md`:
- Around line 24-32: The table uses shortened paths like `core/attribute.py →
to_db()` and `core/query/node.py → NodeCreateFullBatchQuery`, which is
inconsistent with Step 1's repo-root style (e.g., `backend/infrahub/...`);
update each entry in the write-path table to the full repo-root paths matching
the commands in Step 1 (for example replace `core/attribute.py` with the full
path under `backend/infrahub/...` and similarly expand
`core/query/resource_manager.py`, `core/migrations/graph/m0*.py`,
`core/migrations/schema/*.py`, and `core/migrations/query/*.py`) so copy/paste
navigation is accurate and consistent.

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 826e606 and 39e2c03.

📒 Files selected for processing (5)

backend/AGENTS.md
dev/guides/backend/adding-node-properties.md
dev/guides/backend/writing-migrations.md
dev/knowledge/backend/database-schema.md
dev/knowledge/backend/query-pattern.md

dev/knowledge/backend/database-schema.md

codspeed-hq · 2026-02-27T13:40:19Z

Merging this PR will not alter performance

✅ 12 untouched benchmarks

_{Comparing pog-dev-docs-neo4j-write-paths (550bb14) with develop (826e606)}

Replace "O(1)-ish" with "index-backed, avoids full scans" for the TEXT index CONTAINS example, which more accurately reflects Neo4j query planning behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ajtmccarty

I think this could be helpful, but I am not really sure. I am not confident that I can determine what context an LLM needs or when it will use that context

ajtmccarty · 2026-02-27T19:12:08Z

dev/guides/backend/adding-node-properties.md

I think this is a good guide for adding a new required property that needs to be backfilled, but it should make it clear that it is just for that case

we have added optional properties in the past that don't require a migration or backfilling and we just have optional handling to check if the property is set or set it to a default value when getting it from the db

ajtmccarty · 2026-02-27T19:20:05Z

dev/guides/backend/writing-migrations.md

I'd say this is specifically for writing graph migrations, which the test kind of says implicitly
we also include "database" migrations where we make changes using a mix of cypher and Python or just using existing Python code, in which case this document might not apply

ajtmccarty · 2026-02-27T19:22:28Z

dev/knowledge/backend/database-schema.md

+- Queries that filter on a property will silently exclude nodes that lack it
+- TEXT and RANGE indexes only index nodes that **have** the indexed property — a node without the property is invisible to index-backed queries
+
+**Mitigation:** Maintain a write path registry (see [AttributeValueIndexed Write Paths](#attributevalueindexed-write-paths)) and audit all paths when adding properties.


this seems likely to be forgotten and get out of date, but perhaps LLMs can help us keep it up-to-date

BeArchiTek requested a review from a team as a code owner February 27, 2026 13:34

github-actions bot added the group/backend Issue related to the backend (API Server, Git Agent) label Feb 27, 2026

coderabbitai bot reviewed Feb 27, 2026

View reviewed changes

dev/knowledge/backend/database-schema.md Outdated Show resolved Hide resolved

BeArchiTek self-assigned this Feb 27, 2026

docs: fix misleading O(1) asymptotic claim in database schema docs

550bb14

Replace "O(1)-ish" with "index-backed, avoids full scans" for the TEXT index CONTAINS example, which more accurately reflects Neo4j query planning behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ajtmccarty reviewed Feb 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add dev docs for Neo4j#8501

Add dev docs for Neo4j#8501
BeArchiTek wants to merge 2 commits intodevelopfrom
pog-dev-docs-neo4j-write-paths

BeArchiTek commented Feb 27, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

ajtmccarty left a comment

Uh oh!

ajtmccarty Feb 27, 2026

Uh oh!

ajtmccarty Feb 27, 2026

Uh oh!

ajtmccarty Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

BeArchiTek commented Feb 27, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

ajtmccarty left a comment

Choose a reason for hiding this comment

Uh oh!

ajtmccarty Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

ajtmccarty Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

ajtmccarty Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BeArchiTek commented Feb 27, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 27, 2026 •

edited

Loading

codspeed-hq bot commented Feb 27, 2026 •

edited

Loading