-
Notifications
You must be signed in to change notification settings - Fork 17
docs: extend ENS Unigraph examples #2264
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
82781f3
Apply feedback from Slack and PR 2227
tk-o a309cb7
Setup ENS Unigraph exmaple files
tk-o d4e91df
Extend ENS Unigraph examples
tk-o 5589ee0
Merge remote-tracking branch 'origin/main' into docs/extend-ens-unigr…
tk-o 2b41753
Apply AI PR feedback
tk-o 8b2ce94
Make examples to use latest indexed columns in domains table
tk-o 131bc36
Apply AI PR feedback
tk-o 0a0b6f2
Apply AI PR feedback
tk-o af01c75
Merge remote-tracking branch 'origin/main' into docs/extend-ens-unigr…
tk-o d55072a
Improve ENS Unigraph examples
tk-o 97c5302
Improve ENS Unigraph examples
tk-o 312e4c2
Fix codestyle issue
tk-o ffd5a50
Apply AI PR feedback
tk-o d568058
Apply AI PR feedback
tk-o c9cef02
Merge remote-tracking branch 'origin/main' into docs/extend-ens-unigr…
tk-o File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
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
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
9 changes: 9 additions & 0 deletions
9
docs/ensnode.io/src/components/molecules/EnsUnigraphIntro.astro
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| import { Aside } from "@astrojs/starlight/components"; | ||
| --- | ||
|
|
||
| <Aside type="tip" title="What is the ENS Unigraph?"> | ||
| Explore an <a href="/docs/integrate/unigraph">overview</a> and <a | ||
| href="/docs/integrate/unigraph/concepts">core concepts</a | ||
| > to learn about the ENS Unigraph. | ||
| </Aside> |
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
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
47 changes: 47 additions & 0 deletions
47
docs/ensnode.io/src/content/docs/docs/integrate/unigraph/concepts.mdx
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| --- | ||
| title: ENS Unigraph Core Concepts | ||
| description: The core concepts behind the ENS Unigraph indexed data model. | ||
| --- | ||
|
|
||
| ## Indexed Data Model | ||
|
|
||
| The ENS Unigraph indexed data model is available only when the [`unigraph` plugin](/docs/integrate/integration-options/ensnode-plugins#existing-plugins) is activated in your ENSNode instance. | ||
|
|
||
| :::caution[`unigraph` plugin required] | ||
| Performing SQL queries on the ENS Unigraph requires that you have the `unigraph` plugin activated in your ENSNode instance. [Learn more](/docs/services/ensindexer/usage/configuration) about activating [ENSNode Plugins](/docs/integrate/integration-options/ensnode-plugins). | ||
| ::: | ||
|
|
||
| ## Canonical Nametree | ||
|
|
||
| The **Canonical Nametree** is the set of all Domains that have an inferrable **Canonical Name** — materialized from the namegraph. For every Domain in it, the canonical fields are populated — `canonical_name`, `canonical_path`, `canonical_node`, and `canonical_depth` — across both ENSv1 and ENSv2. That means you can look a name up by `canonical_name = 'vitalik.eth'`, order by `canonical_depth`, or walk a name's path **without branching by `type` on protocol version** and without traversing the namegraph yourself. | ||
|
|
||
| Multichain coverage is part of the same model: Basenames (`.base.eth`), Lineanames (`.linea.eth`), and 3DNS names (`.box`) are materialized into the same Unigraph as mainnet `.eth`, so a single query spans every indexable name. | ||
|
|
||
| :::danger[Not a substitute for ENS Resolution] | ||
| The Unigraph mirrors onchain state; ENS's resolution-time behavior is applied _on top_ of it by | ||
| [ENSApi](/docs/services/ensapi). A direct SQL read of resolver records is therefore **not** | ||
| ENSIP-10 / CCIP-Read compliant and **cannot** be used as a source of truth for name resolution. | ||
| For correct resolution, use the [ENS Omnigraph API](/docs/integrate/omnigraph) (which adds ENS | ||
| Protocol Acceleration on top of the Unigraph). Use Unigraph SQL for analytics, discovery, and | ||
| custom indexing. | ||
| ::: | ||
|
|
||
| ## Query optimizations | ||
|
|
||
| ### Domains | ||
|
|
||
| A `canonical_name` can be very long, as it's the full, correct name. Due to limitations in Postgres btree indexes, the `domains` table has the `canonical_name` column and also the `__canonical_name_prefix` column (the first 64 code points of `canonical_name`, backed by a GIN trigram index). | ||
|
|
||
| :::tip[Searching vs. displaying] | ||
| Always **select and display `canonical_name`**. When you need to **search** by prefix (`ILIKE 'vit%'`, case-insensitive to match the Omnigraph `starts_with` filter), match against the materialized `__canonical_name_prefix` column (the first 64 code points of `canonical_name`, backed by a GIN trigram index) so the `ILIKE` filter is index-backed: | ||
|
|
||
| ```sql | ||
| SELECT id, type, canonical_name, canonical_node, owner_id | ||
| FROM ensindexer_0.domains | ||
| WHERE __canonical_name_prefix ILIKE 'vit%' | ||
| ORDER BY __canonical_name_prefix | ||
| LIMIT 10; | ||
| ``` | ||
|
|
||
| The `SELECT` still returns `canonical_name`; only the `ILIKE` / `ORDER BY` use the prefix. The GIN trigram index backs the `ILIKE` filter; the `ORDER BY` then sorts the matched set (cheap under a small `LIMIT`) — scope the query by `registry_id` to use the `(registry_id, __canonical_name_prefix, id)` btree for fully index-backed ordering. For exact matches, use `canonical_name` directly (`canonical_name = 'vitalik.eth'`). | ||
| ::: |
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
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
27 changes: 27 additions & 0 deletions
27
.../ensnode.io/src/content/docs/docs/integrate/unigraph/examples/domain-events.mdx
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| --- | ||
| title: Domain Events | ||
| description: Fetch recent events for a Domain from the ENS Unigraph by its canonical name. | ||
| sidebar: | ||
| label: Domain Events | ||
| --- | ||
|
|
||
| import UnigraphStaticExample from "@components/molecules/unigraph-static-example/UnigraphStaticExample.astro"; | ||
| import EnsDbWriterSchemaIntro from "@components/molecules/EnsDbWriterSchemaIntro.astro"; | ||
| import EnsDbReaderIntro from "@components/molecules/EnsDbReaderIntro.astro"; | ||
| import { exampleDomainEvents } from "@data/unigraph-examples/domain-events"; | ||
|
|
||
| Fetch recent events for a Domain by its canonical name. This example joins the `events`, `domain_events`, and `domains` tables to retrieve domain events associated with the `vitalik.eth` name. See [Connect](/docs/integrate/unigraph/examples) for setup. | ||
|
|
||
| :::caution[Raw event data] | ||
| The `events` table contains low-level onchain event data, which may require additional processing to interpret. For example, the `data` field is a hex string of ABI-encoded event data that may need to be decoded based on the event type (see `selector` field) to extract meaningful details about the event. | ||
|
|
||
| In the future, the ENS Unigraph may include data referencing higher-level event types (e.g., `DomainRegistered`, `DomainTransferred`, etc.) to simplify querying for common events without needing to parse raw event data. For now, use `selector`, `topics`, and `data` fields in the `events` table to filter and interpret events based on your app's needs. | ||
| ::: | ||
|
|
||
| <UnigraphStaticExample | ||
| sql={exampleDomainEvents.sql} | ||
| ensDbSdk={exampleDomainEvents.sdk} | ||
| > | ||
| <EnsDbWriterSchemaIntro ensDbWriterSchemaName="ensindexer_0" slot="sql-tab-note"/> | ||
| <EnsDbReaderIntro slot="ensdb-sdk-tab-note"/> | ||
| </UnigraphStaticExample> |
21 changes: 21 additions & 0 deletions
21
.../content/docs/docs/integrate/unigraph/examples/domains-fuzzy-search-by-name.mdx
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| --- | ||
| title: Fuzzy Search for ENS Names | ||
| description: Perform a fuzzy search for ENS names. | ||
| sidebar: | ||
| label: Fuzzy Search | ||
| --- | ||
|
|
||
| import UnigraphStaticExample from "@components/molecules/unigraph-static-example/UnigraphStaticExample.astro"; | ||
| import EnsDbWriterSchemaIntro from "@components/molecules/EnsDbWriterSchemaIntro.astro"; | ||
| import EnsDbReaderIntro from "@components/molecules/EnsDbReaderIntro.astro"; | ||
| import { exampleDomainsFuzzySearchByName } from "@data/unigraph-examples/domains-fuzzy-search-by-name"; | ||
|
|
||
| Fetch Domains with names similar to a query string, ranked by similarity. This example uses PostgreSQL's `pg_trgm` extension, which provides the `%` operator for fuzzy matching and the `similarity()` function for ranking results. See [Connect](/docs/integrate/unigraph/examples) for setup. | ||
|
|
||
| <UnigraphStaticExample | ||
| sql={exampleDomainsFuzzySearchByName.sql} | ||
| ensDbSdk={exampleDomainsFuzzySearchByName.sdk} | ||
| > | ||
| <EnsDbWriterSchemaIntro ensDbWriterSchemaName="ensindexer_0" slot="sql-tab-note"/> | ||
| <EnsDbReaderIntro slot="ensdb-sdk-tab-note"/> | ||
| </UnigraphStaticExample> |
21 changes: 21 additions & 0 deletions
21
...io/src/content/docs/docs/integrate/unigraph/examples/expiring-registrations.mdx
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| --- | ||
| title: Expiring ENS Registrations | ||
| description: Fetch ENS registrations that are about to expire. | ||
| sidebar: | ||
| label: Expiring Registrations | ||
| --- | ||
|
|
||
| import UnigraphStaticExample from "@components/molecules/unigraph-static-example/UnigraphStaticExample.astro"; | ||
| import EnsDbWriterSchemaIntro from "@components/molecules/EnsDbWriterSchemaIntro.astro"; | ||
| import EnsDbReaderIntro from "@components/molecules/EnsDbReaderIntro.astro"; | ||
| import { exampleExpiringRegistrations } from "@data/unigraph-examples/expiring-registrations"; | ||
|
|
||
| Fetch Domains with registrations expiring within a certain timeframe. This example uses a simple `WHERE` clause to filter for Domains with `expiry` between the current time and a specified future time (e.g., 3 days from now). See [Connect](/docs/integrate/unigraph/examples) for setup. | ||
|
|
||
| <UnigraphStaticExample | ||
| sql={exampleExpiringRegistrations.sql} | ||
| ensDbSdk={exampleExpiringRegistrations.sdk} | ||
| > | ||
| <EnsDbWriterSchemaIntro ensDbWriterSchemaName="ensindexer_0" slot="sql-tab-note"/> | ||
| <EnsDbReaderIntro slot="ensdb-sdk-tab-note"/> | ||
| </UnigraphStaticExample> |
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.