Domain by Name

unigraph plugin required

Performing SQL queries on the ENS Unigraph requires that you have the unigraph plugin activated in your ENSNode instance. Learn more

Fetch a Domain by its canonical name. Because canonical_name is materialized across both ENSv1 and ENSv2, the same lookup works regardless of protocol version. See Connect for setup.

Searching vs. displaying

A canonical_name can be very long, but it’s the full, correct name — 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:

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').

Canonical fields

Canonical fields are populated on every Domain reachable from the canonical root, across both ENSv1 and ENSv2 — query them uniformly without branching by type. In SQL, these columns are canonical_name, canonical_path, canonical_node, and canonical_depth; in ensdb-sdk, the corresponding fields are canonicalName, canonicalPath, canonicalNode, and canonicalDepth.

SQL

What is an `ensindexer_0`?

It is the name of an ENSDb Writer Schema, which is a database schema within an ENSDb instance, used to store indexed ENS data from a given ENSDb Writer instance. We use ensindexer_0 as the ENSDb Writer Schema Name in examples on this page, but your ENSDb Writer instance may be configured to use a different schema name. Make sure to replace ensindexer_0 with the actual schema name used by your ENSDb Writer instance when querying the ENSDb instance directly. For example, ENSIndexer allows configuring its own ENSDb Writer Schema Name with the ENSINDEXER_SCHEMA_NAME environment variable.

SQL

SELECT
  id,
  type,
  canonical_name,
  canonical_node,
  owner_id
FROM "ensindexer_0".domains
WHERE canonical_name = 'eth'
AND canonical = true;

Output

#	id	type	canonical_name	canonical_node	owner_id
1	11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	ENSv1Domain	eth	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	0xa51c9e6efe589407c72984e93b45e35a71a398ec
2	11155111-0x835f0b284e78cd3f358bcf6cba3b53809f09b79e-35894389512221139346028120028875095598761990588366713962827482865183915769856	ENSv2Domain	eth	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	0xffffffffff52d316b7bd028358089bc8066b8f80

Output matches a point in time snapshot of ENSDb result from our "V2 Sepolia" Hosted ENSNode instance. Live output depends on the configuration of your ENSNode instance and also changes that may have happened in ENS since this point in time snapshot example response was captured.

ensdb-sdk (TypeScript)

Connect with ensdb-sdk

See how to connect to ENSDb and get access to the ensDb query builder and ensIndexerSchema schema definition in the Connect example if you haven't already.

TypeScript

import { and, eq } from "drizzle-orm";

const name = "eth";

const domains = await ensDb
  .select({
    id: ensIndexerSchema.domain.id,
    type: ensIndexerSchema.domain.type,
    canonicalName: ensIndexerSchema.domain.canonicalName,
    canonicalNode: ensIndexerSchema.domain.canonicalNode,
    ownerId: ensIndexerSchema.domain.ownerId,
  })
  .from(ensIndexerSchema.domain)
  .where(
    and(
      eq(ensIndexerSchema.domain.canonicalName, name),
      eq(ensIndexerSchema.domain.canonical, true)
    )
  );

console.log(domains);

Output

#	id	type	canonicalName	canonicalNode	ownerId
1	11155111-0xb6fb46e1458915dd828633d91e1df8e4c3f2d4dd-0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	ENSv1Domain	eth	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	0xa51c9e6efe589407c72984e93b45e35a71a398ec
2	11155111-0x835f0b284e78cd3f358bcf6cba3b53809f09b79e-35894389512221139346028120028875095598761990588366713962827482865183915769856	ENSv2Domain	eth	0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae	0xffffffffff52d316b7bd028358089bc8066b8f80

Output matches a point in time snapshot of ENSDb result from our "V2 Sepolia" Hosted ENSNode instance. Live output depends on the configuration of your ENSNode instance and also changes that may have happened in ENS since this point in time snapshot example response was captured.