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 (LIKE 'vit%'), match against the materialized __canonical_name_prefix column (the first 64 code points of canonical_name, backed by a GIN trigram index) so the LIKE filter is index-backed:

SELECT id, type, canonical_name, canonical_node, owner_id
FROM ensindexer_0.domains
WHERE __canonical_name_prefix LIKE 'vit%'
ORDER BY __canonical_name_prefix
LIMIT 10;

The SELECT still returns canonical_name; only the LIKE / ORDER BY use the prefix. The GIN trigram index backs the LIKE 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 = 'vitalik.eth';

Output

#	id	type	canonical_name	canonical_node	owner_id
1	1-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835	ENSv1Domain	vitalik.eth	0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835	0x220866b1a2219f40e72f5c628b65d54268ca3a9d

Output matches a result snapshot; live output depends on your ENSNode instance.

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 section if you haven't already.

TypeScript

import { eq } from "drizzle-orm";

const [vitalik] = 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(eq(ensIndexerSchema.domain.canonicalName, "vitalik.eth"));

console.log(vitalik);

Output

#	id	type	canonicalName	canonicalNode	ownerId
1	1-0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e-0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835	ENSv1Domain	vitalik.eth	0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835	0x220866b1a2219f40e72f5c628b65d54268ca3a9d

Output matches a result snapshot; live output depends on your ENSNode instance.