Saltearse al contenido

Esquema — restricciones e índices

NamiDB tiene un esquema opcional: los labels, los tipos de relación y las propiedades no necesitan declararse. Solo declaras lo que quieres que se haga cumplir o se acelere:

DeclaraciónHace cumplirAcelera
Restricción de unicidadQue dos nodos de un label no compartan el valor (o la tupla)Búsquedas por igualdad y MERGE sobre la clave
ÍndiceNadaBúsquedas por igualdad e IN, rangos numéricos, filtros de búsqueda vectorial
Índice vectorialLa dimensión del embedding al escribirBúsqueda KNN
Índice full-textNadasearch.bm25, la parte de texto de search.hybrid

Las restricciones y los índices se aplican a propiedades de nodos. Las restricciones e índices sobre propiedades de relaciones no están soportados.

Cada sentencia DDL debe ser la única sentencia de su petición (una llamada HTTP, una llamada a cypher(), un run de Bolt). Los scripts separados por ; de la CLI ejecutan cada sentencia por separado, así que ahí un script de esquema funciona.

Restricciones de unicidad

CREATE CONSTRAINT user_email IF NOT EXISTS
FOR (u:User) REQUIRE u.email IS UNIQUE
  • El nombre (user_email) es opcional. Sin él, la restricción se llama uniq_<Label>_<property>.
  • IF NOT EXISTS hace que la sentencia no haga nada cuando ya existe una restricción equivalente. Sin él, volver a declararla falla: a uniqueness constraint on User(email) already exists.
  • La sintaxis de Neo4j 4 también funciona: CREATE CONSTRAINT ON (u:User) ASSERT u.email IS UNIQUE.
  • Declarar una restricción sobre un label que ya contiene valores duplicados falla: cannot create unique constraint on User(email): duplicate (email=Str("a")) already exists.

Una escritura que rompería la restricción se rechaza y se hace rollback de la sentencia completa (HTTP 409, code: "constraint"):

constraint violation: User.email = Str("a@x") already exists (unique constraint)

Unicidad compuesta

CREATE CONSTRAINT cfg_uq IF NOT EXISTS
FOR (c:Config) REQUIRE (c.tenant, c.name) IS UNIQUE

Dos nodos :Config no pueden compartir la misma tupla (tenant, name). La restricción solo se aplica a los nodos que tienen todas las propiedades indicadas; un nodo al que le falta alguna no se verifica.

constraint violation: (tenant = Str("t"), name = Str("n")) already exists (composite unique constraint on Config)

Los valores tienen tipo: el entero 1 y el string '1' son claves distintas.

Índices

// One property:
CREATE INDEX FOR (d:Doc) ON (d.slug)
// A composite (tuple) index, named and idempotent:
CREATE INDEX doc_ts IF NOT EXISTS FOR (d:Doc) ON (d.tenant, d.slug)
// Neo4j 4 spelling:
CREATE INDEX ON :Doc(slug)

Un índice acelera:

  • los filtros de igualdad e IN (WHERE d.slug = $s, {slug: $s}, WHERE d.slug IN $list);
  • una búsqueda compuesta cuando todas las propiedades indexadas están restringidas por igualdad, en cualquier orden (WHERE d.tenant = $t AND d.slug = $s);
  • los predicados de rango sobre propiedades numéricas (WHERE d.score >= 0.5);
  • los filtros de metadatos dentro de search.vector, search.bm25 y search.hybrid (consulta filtros).

Una restricción de unicidad ya proporciona un índice sobre su clave; no necesitas ambos.

Los índices de una sola propiedad aparecen como index_<Label>_<property> en SHOW INDEXES, sin importar el nombre que les hayas dado; los índices compuestos conservan su nombre.

Los índices y las restricciones se pueden declarar antes o después de cargar los datos. Declararlos primero (“esquema, luego carga”) está totalmente soportado, incluso para claves numéricas desde 3.2.0.

Comprueba si una consulta usa un índice con EXPLAIN: una búsqueda por índice aparece como NodeByPropertyValue con una línea # route: en lugar de un NodeScan filtrado:

EXPLAIN MATCH (p:Person {id: 1}) RETURN p
Project [p=p]
NodeByPropertyValue label=Person alias=p id=1
Empty
# route: Person.id → memtable (unique lookup; no SSTs in scope)

Ver lo que está declarado

SHOW CONSTRAINTS
[{"name": "cfg_uq", "type": "UNIQUENESS", "entityType": "NODE",
"labelsOrTypes": ["Config"], "properties": ["tenant", "name"]},
{"name": "u_email", "type": "UNIQUENESS", "entityType": "NODE",
"labelsOrTypes": ["User"], "properties": ["email"]}]
SHOW INDEXES

SHOW INDEXES retorna las mismas columnas, con type RANGE para los índices de propiedades y compuestos (incluido el índice que respalda cada restricción de unicidad de una sola propiedad), VECTOR para los índices vectoriales y FULLTEXT para los índices full-text. Solo se aceptan las formas simples: SHOW CONSTRAINT[S] y SHOW INDEX[ES], sin YIELD, BRIEF ni VERBOSE.

Eliminar

SentenciaElimina
DROP INDEX <name> [IF EXISTS]Un índice full-text
DROP VECTOR INDEX <name> [IF EXISTS]Un índice vectorial

Eliminar una restricción de unicidad o un índice de propiedades no está soportado en 3.3.0 (DROP CONSTRAINT no se parsea, y DROP INDEX solo encuentra índices full-text). Para cambiar uno, carga los datos en un namespace nuevo con el esquema que quieras.

Introspección

ProcedimientoProduce
CALL db.labels()label
CALL db.relationshipTypes()relationshipType
CALL db.propertyKeys()propertyKey
CALL db.schema.visualization()nodes, relationships: un nodo por label, con sus restricciones e índices
CALL db.labels() YIELD label RETURN label

Estos son los procedimientos que llaman las GUIs de grafos y las herramientas de Neo4j cuando se conectan por Bolt.

Un script de migración

Como todas las sentencias de esta página son idempotentes con IF NOT EXISTS, un script de esquema puede ejecutarse en cada despliegue. Con la CLI:

Ventana de terminal
namidb run --store "file:///var/lib/namidb?ns=prod" "
CREATE CONSTRAINT user_email IF NOT EXISTS FOR (u:User) REQUIRE u.email IS UNIQUE;
CREATE CONSTRAINT cfg_uq IF NOT EXISTS FOR (c:Config) REQUIRE (c.tenant, c.name) IS UNIQUE;
CREATE INDEX doc_ts IF NOT EXISTS FOR (d:Doc) ON (d.tenant, d.slug)
"

Contra un servidor en ejecución, envía cada sentencia en su propio POST /v0/cypher.