docs: examples cleanup + integrate restructure (Unigraph SQL, Subgraph as legacy)#2171
Open
shrugs wants to merge 15 commits into
Open
docs: examples cleanup + integrate restructure (Unigraph SQL, Subgraph as legacy)#2171shrugs wants to merge 15 commits into
shrugs wants to merge 15 commits into
Conversation
Removes the orphaned /examples page (not linked in any nav) and its supporting code: - src/pages/examples.astro - src/components/organisms/ExampleCard.astro - src/data/ens-v1-examples-queries.ts (savedQueries) - the `examples` content collection in content.config.ts The Omnigraph API examples (src/data/omnigraph-examples) are unaffected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Show enssdk (simpler integration) before enskit (more complex) in the quickstart, integration-options overview, and sidebar. Omnigraph GraphQL API stays in its position after both. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The schema models the unified ENSv1 + ENSv2 "Unigraph" data model, built by the unigraph plugin. Rename the file (and its doc-comment title) to match the "Unigraph" terminology used elsewhere. No exported symbols change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restructure the "Integrate with ENSv2" docs around three pillars: - ENS Unigraph SQL: new section (Overview, Examples in SQL + ensdb-sdk, canonical Schema Reference moved from the ENSDb service docs). Green NEW badge. - ENS Omnigraph API: badge recolored green (was pink). - ENS Subgraph: moved out of Reference into Integrate with a red LEGACY badge; overview reframed around its ENSv2 shortcomings (ENSv1-only, single-chain, no resolution). Old URLs redirect to the new paths. The Unigraph schema reference is now canonical under integrate/unigraph; the ENSDb database-schemas page links to it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
3 Skipped Deployments
|
|
Contributor
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThis PR implements a comprehensive documentation restructuring: removes the legacy Examples browsing feature entirely, migrates Subgraph documentation from reference to integrate paths while marking it as legacy, introduces Unigraph SQL as the forward integration path with full schema reference and examples, reorders integration options to prioritize enssdk, refactors GraphQL schema explorers into a reusable component, enhances Omnigraph example queries with beautified canonical field support, and updates SDK schema terminology from ensv2 to unigraph. ChangesDocumentation Restructuring, Examples Removal, and Unigraph Introduction
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the “Integrate with ENSv2” documentation into clearer integration pillars (leading with enssdk/enskit, adding Unigraph SQL as a first-class option) and removes legacy ENSv1 Subgraph example pages/data. It also renames the ENSDb SDK’s internal “ENSv2 schema” terminology to “Unigraph” (without intended API/behavior changes).
Changes:
- Remove legacy ENSv1 Subgraph “examples” page/data and expand Omnigraph example queries.
- Add new “ENS Unigraph SQL” docs section (overview, examples, and canonical schema reference), and link ENSDb schema docs to it.
- Move Subgraph docs into Integrate as “LEGACY” with redirects and updated sidebar organization; rename schema file references from ENSv2 → Unigraph.
Reviewed changes
Copilot reviewed 23 out of 27 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/ensnode-sdk/src/omnigraph-api/example-queries.ts | Adds/updates Omnigraph GraphQL example queries (incl. beautified names, registration, pagination, resolver-by-address). |
| packages/ensdb-sdk/src/ensindexer-abstract/unigraph.schema.ts | Updates schema header/docs to “Unigraph” terminology. |
| packages/ensdb-sdk/src/ensindexer-abstract/index.ts | Re-exports Unigraph schema from the abstract ENSIndexer schema index. |
| docs/ensnode.io/src/pages/examples.astro | Removes the legacy examples listing page. |
| docs/ensnode.io/src/data/ens-v1-examples-queries.ts | Removes legacy ENSv1 Subgraph example query dataset. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/database-schemas.mdx | Replaces duplicated Unigraph/ENSv2 schema reference with a link to the new canonical Unigraph schema docs page. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdx | Adds canonical Unigraph table-by-table schema reference under Integrate. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/index.mdx | Adds “ENS Unigraph SQL” overview page. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/indexing-status.mdx | Adds Unigraph SQL example for reading indexing status (SQL + ensdb-sdk). |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/index.mdx | Adds Unigraph SQL examples landing page and connection instructions. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/domain-by-name.mdx | Adds example for fetching a domain by canonical name (SQL + ensdb-sdk). |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/account-domains.mdx | Adds example for counting an account’s domains grouped by protocol version (SQL + ensdb-sdk). |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/with-viem.mdx | Adds integration notes for libraries that rely on viem/chain Subgraph URL configuration. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/with-ensjs.mdx | Adds ENSjs integration page for Subgraph-compatible endpoint usage. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/what-is-the-ens-subgraph.mdx | Reframes Subgraph docs as legacy and updates internal links to new Integrate paths. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-dependents.mdx | Adds “dependents” ecosystem/impact page for the Subgraph. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-compatibility-tooling.mdx | Adds page documenting compatibility verification tooling. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-api.mdx | Updates link paths to new Integrate Subgraph location. |
| docs/ensnode.io/src/content/docs/docs/integrate/subgraph/querying-best-practices.mdx | Updates link paths to new Integrate Subgraph location. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdx | Reorders integration options to lead with enssdk. |
| docs/ensnode.io/src/content/docs/docs/integrate/index.mdx | Reorders and updates the top-level Integrate page to lead with enssdk, then enskit, then Omnigraph API. |
| docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx | Updates Subgraph link to new Integrate Subgraph path. |
| docs/ensnode.io/src/content.config.ts | Removes the deleted examples content collection. |
| docs/ensnode.io/src/components/organisms/ExampleCard.astro | Removes legacy examples UI component. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts | Removes legacy Subgraph section from Reference sidebar. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts | Adds Unigraph SQL section, moves Subgraph under Integrate with LEGACY badge, and reorders Integration Options. |
| docs/ensnode.io/astro.config.mjs | Adds/updates redirects from old Subgraph legacy paths to new Integrate Subgraph paths. |
Comments suppressed due to low confidence (1)
docs/ensnode.io/src/content/docs/docs/integrate/subgraph/what-is-the-ens-subgraph.mdx:13
- This section references “Summer 2026” as a launch date. Since that date is in the future relative to the current docs build, consider rephrasing to something like “planned/expected in Summer 2026” (or removing the specific date) to avoid the docs becoming stale if timelines change.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/subgraph/querying-best-practices.mdx`:
- Line 142: Update the inline link labeled "Subgraph Compatibility" so it
deep-links to the configuration section anchor on the Subgraph overview page
(the same fragment used in subgraph-api.mdx) instead of landing at the top;
change the href for the existing
/docs/integrate/subgraph/what-is-the-ens-subgraph link to include the
`#subgraph-compatibility` fragment so readers are taken directly to the
SUBGRAPH_COMPAT configuration section.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/indexing-status.mdx`:
- Around line 14-20: The SQL example includes an overly specific WHERE clause
filtering value -> 'indexingStatus' -> 'omnichainSnapshot' ->> 'omnichainStatus'
= 'omnichain-backfill'; remove that condition so the query returns the full
indexingStatus for the ensindexer_0 schema (i.e., keep SELECT value ->
'indexingStatus' FROM "ensnode"."metadata" WHERE ens_indexer_schema_name =
'ensindexer_0' AND key = 'indexing_metadata_context';) or, if you prefer to keep
it as an example of optional filtering, add a short inline comment next to the
omnichainStatus filter explaining it is optional and can be adjusted to target a
specific state.
In `@packages/ensnode-sdk/src/omnigraph-api/example-queries.ts`:
- Around line 232-251: The SubdomainsPagination GraphQL query hardcodes
domain(by: { name: "eth" }) which breaks non-mainnet namespaces; change the
query to accept a parameter (e.g., add $name: InterpretedName! to the query
signature and use domain(by: { name: $name })) and update the example-queries
entry for SubdomainsPagination to provide per-namespace variable overrides
(modify the variables.default to include a name value and mirror how
`domain-events`/`domains-by-address` supply namespace-specific variable values)
so each namespace can pass its root name.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 437245f4-bd59-4691-8e1a-670c43b59135
📒 Files selected for processing (27)
docs/ensnode.io/astro.config.mjsdocs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.tsdocs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.tsdocs/ensnode.io/src/components/organisms/ExampleCard.astrodocs/ensnode.io/src/content.config.tsdocs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdxdocs/ensnode.io/src/content/docs/docs/integrate/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/querying-best-practices.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-api.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-compatibility-tooling.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/subgraph-dependents.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/what-is-the-ens-subgraph.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/with-ensjs.mdxdocs/ensnode.io/src/content/docs/docs/integrate/subgraph/with-viem.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/account-domains.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/domain-by-name.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/examples/indexing-status.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/database-schemas.mdxdocs/ensnode.io/src/data/ens-v1-examples-queries.tsdocs/ensnode.io/src/pages/examples.astropackages/ensdb-sdk/src/ensindexer-abstract/index.tspackages/ensdb-sdk/src/ensindexer-abstract/unigraph.schema.tspackages/ensnode-sdk/src/omnigraph-api/example-queries.ts
💤 Files with no reviewable changes (5)
- docs/ensnode.io/src/components/organisms/ExampleCard.astro
- docs/ensnode.io/src/data/ens-v1-examples-queries.ts
- docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts
- docs/ensnode.io/src/content.config.ts
- docs/ensnode.io/src/pages/examples.astro
- unigraph SQL: require a self-hosted ENSDb (drop hosted-instance tip), point to the self-hosting overview and the Omnigraph API for hosted access - reframe canonicality around the materialized Canonical Nametree (overview, schema reference, and the unigraph.schema.ts comment) - permissions: "who can do what in a specific contract" - move the ENS Subgraph sidebar group below Integration Options - address review nits: deep-link the subgraph compatibility anchor; drop the omnichain-backfill filter from the indexing-status SQL example - add changeset for @ensnode/ensnode-sdk + @ensnode/ensdb-sdk Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
Contributor
Greptile SummaryThis PR restructures the ENSNode docs around three integration pillars (ENS Unigraph SQL, ENS Omnigraph API, and the legacy Subgraph), adds a new Unigraph SQL section with schema reference and examples, moves Subgraph docs to
Confidence Score: 5/5Safe to merge — docs-only restructure with a narrow, low-risk schema file rename and one strengthened contract lookup. All changed code is documentation content or thin adapter components. The one code-path change — swapping maybeGetDatasourceContract (returns undefined) for getDatasourceContract (throws) on four module-level constants — is correct: all referenced contracts (ETHRegistry, ETHRegistrar, DefaultPublicResolver5) are confirmed present in their respective namespace datasources, so the stricter call will never throw in practice and gives an earlier, clearer failure if a future datasource change removes one. Redirect coverage is complete: every old reference/subgraph-legacy/* URL and every flat integrate/subgraph/* URL maps to a real target in the new tree, and no redirect chains were introduced. No files require special attention. Important Files Changed
Reviews (12): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile |
- move ENS Subgraph nav section above ENS Omnigraph API (collapsed); mirror Omnigraph nav order (Overview → Examples → Schema Reference) - rename what-is-the-ens-subgraph → subgraph overview (index), retitle "Overview of Legacy Subgraph API" - rename subgraph-api → schema-reference: remove examples, add interactive GraphQL DocExplorer over the introspected (locked) subgraph SDL, harmonized with the Omnigraph schema reference; extract shared GraphQLSchemaDocExplorer - add Examples subsection (overview + with-ensjs + with-viem) - inline Subgraph Compatibility Tooling content into Overview; delete its page - rename ens-app-v3 prose refs → "ENSv1 Manager App"; drop now-implemented _Meta_ from unplanned features - update internal links, redirects, and llms-txt excludes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Example $contract/$registry variables are declared AccountIdInput! (non-null), so use the throwing getDatasourceContract instead of maybeGetDatasourceContract to close the type-safety gap and fail fast if a contract is ever missing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
Author
|
@greptile review |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 30 out of 34 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
docs/ensnode.io/src/content/docs/docs/integrate/subgraph/index.mdx:12
- This references an ENSv2 launch date in the future (“Summer 2026”). Time-bound dates in docs tend to go stale quickly; consider switching to a relative phrasing (e.g. “when ENSv2 launches”) or linking to a maintained announcement page instead of embedding a specific season/year.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
Author
|
@greptile review |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 30 out of 34 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
docs/ensnode.io/src/content/docs/docs/integrate/subgraph/index.mdx:74
- Minor wording/typo: “blockheights” should be “block heights”.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #1917
restructures the "integrate with ensv2" docs around three clear pillars and cleans up the legacy examples. docs-only plus one internal schema-file rename; no api or behavior changes.
what changed
examples cleanup (pre-existing checkpoints on this branch)
examples.astro,ens-v1-examples-queries.ts,ExampleCard.astro, content.config entries)integration options reorder
enssdk(simpler) →enskit→ omnigraph graphql apielevate ENS Unigraph SQL
database-schemaspage links to it instead of duplicatingreframe the Subgraph as legacy
reference/intointegrate/subgraph/with a red LEGACY badge/docs/reference/subgraph-legacy/*urls redirect to the new pathsschema rename
ensv2.schema.ts→unigraph.schema.tsin@ensnode/ensdb-sdkto match the "Unigraph" terminology. no exported symbols change.validation