NQL — Nietzsche Query Language

Manual de Referencia Completo

Versao: 3.1 (NQL v3.1 — Fases 1-11 + NQL 3.0 Sprint + PostgreSQL-inspired Features) Banco: NietzscheDB — Multi-Manifold Graph Database (Poincaré · Klein · Riemann · Minkowski) Parser: pest (PEG Grammar) em Rust Repositorio: github.com/JoseRFJuniorLLMs/NietzscheDB

---

NQL e a primeira linguagem de query com primitivas hiperbolicas nativas, funcoes matematicas eponymous — nomeadas em homenagem aos matematicos e fisicos cujo trabalho fundamenta o NietzscheDB — e funcoes cognitivas nomeadas em homenagem a Boltzmann, Helmholtz, Lyapunov, Prigogine e Erdos. Nao e uma extensao de Cypher, SQL ou SPARQL. E uma linguagem nova, construida para um substrato de memoria que nao existia antes.

---

Indice

1. Conceitos Fundamentais
2. Tipos de Dados
3. Statements
   • MATCH
   • OPTIONAL MATCH
   • DIFFUSE
   • RECONSTRUCT
   • EXPLAIN
   • UNION / UNION ALL
   • UNWIND
   • SHORTEST_PATH
   • MATCH ELITES
   • MEASURE TENSION / MEASURE TGC
   • FIND NEAREST
4. Operadores de Distancia
   • HYPERBOLIC_DIST
   • SENSORY_DIST
5. Funcoes Matematicas Eponymous
   • POINCARE_DIST
   • KLEIN_DIST
   • MINKOWSKI_NORM
   • LOBACHEVSKY_ANGLE
   • RIEMANN_CURVATURE
   • GAUSS_KERNEL
   • CHEBYSHEV_COEFF
   • RAMANUJAN_EXPANSION
   • HAUSDORFF_DIM
   • EULER_CHAR
   • LAPLACIAN_SCORE
   • FOURIER_COEFF
   • DIRICHLET_ENERGY
6. Funcoes Cognitivas Eponymous (NQL 3.0)
   • BOLTZMANN_SURVIVAL
   • HELMHOLTZ_GRADIENT
   • LYAPUNOV_DELTA
   • PRIGOGINE_BASIN
   • ERDOS_EDGE_PROB
7. Funcoes Built-in (NQL 3.0)
   • String
   • Math
   • Cast
   • Null
8. Condicoes Avancadas (NQL 3.0)
   • IS NULL / IS NOT NULL
   • Regex (=~)
   • EXISTS subquery
   • CASE WHEN
9. Clausulas e Operadores
   • WHERE
   • ORDER BY
   • LIMIT / SKIP
   • RETURN
   • DISTINCT
   • AS (alias)
   • IN
   • BETWEEN
   • CONTAINS / STARTS_WITH / ENDS_WITH
   • AND / OR / NOT
10. Agregacoes
    • COUNT / SUM / AVG / MIN / MAX
    • COLLECT
    • GROUP BY
11. Planner — Como NQL decide a estrategia
12. Parametros e Variaveis
13. Comparacao com outras linguagens
14. Exemplos por dominio
15. Erros e diagnostico
16. Referencia rapida
17. NQL 3.1: PostgreSQL-inspired Features
    • CTEs (WITH ... AS)
    • Window Functions
    • Views
    • Materialized Views
    • RETURNING Clause
    • CHECK Constraints
    • UNIQUE Indexes
    • Prepared Statements
    • LATERAL Subquery
    • Table Partitioning

---

1. Conceitos Fundamentais

O espaco onde NQL opera

NQL nao opera em tabelas, nem em documentos, nem em grafos euclidianos. Opera na Bola de Poincare — um espaco hiperbolico onde:

Centro da bola  ->  conceitos abstratos, categorias gerais
Fronteira       ->  instancias especificas, memorias episodicas

Regra invariante: ||x|| < 1.0 para todo embedding

Toda distancia calculada pelo NQL e distancia hiperbolica:

d(u,v) = arcosh(1 + 2||u-v||^2 / ((1-||u||^2)(1-||v||^2)))

Isso significa que a mesma query retorna resultados diferentes de um banco euclidiano — ela entende hierarquia geometricamente, nao por metadados.

Os tres objetos fundamentais

No (Node): A unidade basica de memoria. Contem um embedding hiperbolico, metadados JSON, energia, profundidade, dimensao de Hausdorff local e opcionalmente um payload sensorial (Fase 11).

Aresta (Edge): Relacao tipada entre dois nos. Tipos: Association, Hierarchical, LSystemGenerated, Pruned.

Grafo: O conjunto vivo de nos e arestas. Nao e estatico — cresce via L-System, e podado via Hausdorff e se reconsolida via ciclo de sono.

A energia dos nos

Todo no tem energy in [0.0, 1.0]:

1.0  ->  no recem-criado, maxima vitalidade
0.7  ->  no ativo, regularmente acessado
0.5  ->  no em decaimento, menos relevante
0.3  ->  no esquecendo — payload sensorial degradado
0.1  ->  apenas o embedding sobrevive
0.0  ->  poda — no removido do grafo

Propriedades acessiveis dos nos

---

2. Tipos de Dados

Primitivos

Tipos compostos

PoincareVector: vetor com invariante ||x|| < 1.0 garantida.

Modality (Fase 11):

Image | Audio | Text | Fused

Parametros

Variaveis externas prefixadas com $:

$query_vec     -- vetor de embedding (PoincareVector)
$node_id       -- UUID de um no especifico
$threshold     -- valor numerico passado pelo cliente
$text          -- string passada pelo cliente
$t             -- escalar para funcoes parametricas

---

3. Statements

3.1 MATCH

Busca nos no grafo com filtros, ordenacao, agregacao e paginacao.

Sintaxe completa:

MATCH (alias[:Label])
[WHERE condicao]
RETURN [DISTINCT] expressao [AS nome] [, ...]
[GROUP BY campo [, ...]]
[ORDER BY expressao ASC|DESC]
[LIMIT n]
[SKIP n]

Exemplo minimo:

MATCH (m:Memory)
WHERE m.energy > 0.0
RETURN m
LIMIT 10

Com filtro hiperbolico:

MATCH (m:Memory)
WHERE HYPERBOLIC_DIST(m.embedding, $query_vec) < 0.5
RETURN m
ORDER BY HYPERBOLIC_DIST(m.embedding, $query_vec) ASC
LIMIT 10

Com filtros compostos:

MATCH (m:Memory)
WHERE HYPERBOLIC_DIST(m.embedding, $query_vec) < 0.5
  AND m.depth > 0.6
  AND m.energy > 0.3
RETURN m
ORDER BY m.depth DESC
LIMIT 20

Com funcao matematica:

MATCH (n)
WHERE POINCARE_DIST(n.embedding, $q) < 0.5
  AND MINKOWSKI_NORM(n.embedding) > 2.0
RETURN n
ORDER BY POINCARE_DIST(n.embedding, $q) ASC
LIMIT 10

Traversal com arestas:

MATCH (a)-[:Association]->(b)
WHERE a.energy > 0.5
RETURN b

Aresta anonima:

MATCH (a)-->(b)
WHERE a.energy > 0.5
RETURN b
LIMIT 15

Direcao inversa:

MATCH (a)<-[:Hierarchical]-(b)
WHERE a.energy > 0.3
RETURN a, b

Com agregacao:

MATCH (n:Memory)
WHERE n.energy > 0.0
RETURN n.node_type, COUNT(*) AS total, AVG(n.energy) AS avg_e
GROUP BY n.node_type

Com paginacao:

MATCH (n)
WHERE n.energy > 0.3
RETURN n
ORDER BY n.energy DESC
LIMIT 10
SKIP 20

Com DISTINCT:

MATCH (n:Memory)
WHERE n.energy > 0.5
RETURN DISTINCT n
LIMIT 50

Com IN:

MATCH (n)
WHERE n.energy IN (0.3, 0.5, 0.8)
RETURN n

Com BETWEEN:

MATCH (n)
WHERE n.energy BETWEEN 0.3 AND 0.8
RETURN n

Com operadores de string:

MATCH (n)
WHERE n.id CONTAINS "abc"
RETURN n

MATCH (n)
WHERE n.node_type STARTS_WITH "Mem"
RETURN n

MATCH (n)
WHERE n.id ENDS_WITH "f00"
RETURN n

---

3.2 OPTIONAL MATCH (NQL 3.0)

Busca padrao opcional — equivalente a LEFT OUTER JOIN em SQL. Se o padrao nao encontrar correspondencia, as variaveis vinculadas retornam NULL em vez de eliminar a linha.

Sintaxe:

MATCH (a[:Label])
OPTIONAL MATCH (a)-[:TYPE]->(b)
[WHERE condicao]
RETURN a, b

Exemplos:

-- Retornar todas as pessoas, mesmo sem conexoes
MATCH (p:Concept)
OPTIONAL MATCH (p)-[:Association]->(related)
RETURN p, related

-- Com filtro no padrao opcional
MATCH (n:Semantic)
OPTIONAL MATCH (n)-[:Hierarchical]->(child)
WHERE child.energy > 0.5
RETURN n, child

Diferenca do MATCH: No MATCH normal, se o padrao de aresta nao encontra correspondencia, a linha inteira e eliminada. No OPTIONAL MATCH, a linha e mantida com b = NULL.

---

3.3 DIFFUSE

Propaga ativacao pelo grafo via heat kernel hiperbolico. Retorna nos ativados em multiplas escalas de difusao.

Conceito central:

t pequeno  ->  ativa vizinhos proximos (recall especifico)
t grande   ->  ativa nos distantes semanticamente (associacao livre)

Sintaxe completa:

DIFFUSE FROM $param | alias
  [WITH t = [t1, t2, ..., tn]]
  [MAX_HOPS n]
  [RETURN expressao [, ...]]

Exemplo basico:

DIFFUSE FROM $node_id
  WITH t = [0.1, 1.0, 10.0]
  MAX_HOPS 5
RETURN path

Minimo:

DIFFUSE FROM $n
RETURN path

O que cada escala t significa na pratica:

---

3.4 RECONSTRUCT (Fase 11)

Reconstroi a experiencia sensorial de um no a partir do latent armazenado.

Sintaxe:

RECONSTRUCT $param | alias
  [MODALITY nome]
  [QUALITY nivel]

Exemplos:

-- Completo
RECONSTRUCT $session_node_id
  MODALITY audio
  QUALITY high

-- Minimo
RECONSTRUCT $nid

-- So modalidade
RECONSTRUCT $n MODALITY text

Qualidade disponivel depende de energy:

---

3.5 EXPLAIN

Retorna o plano de execucao de uma query sem executa-la. Util para diagnostico e otimizacao.

Sintaxe:

EXPLAIN <query>

Exemplos:

EXPLAIN MATCH (n:Memory)
  WHERE n.energy > 0.3
  RETURN n
  ORDER BY n.energy DESC
  LIMIT 10

-- Retorna:
-- NodeScan(label=Memory) -> Filter(conditions=1) -> Sort(dir=Desc) -> Limit(10)

EXPLAIN MATCH (a)-[:Association]->(b)
  WHERE a.energy > 0.5
  RETURN b

-- Retorna:
-- EdgeScan(type=Association, dir=-->) -> Filter(conditions=1)

EXPLAIN DIFFUSE FROM $n MAX_HOPS 5 RETURN path

-- Retorna:
-- DiffusionWalk(max_hops=5, t_scales=1)

EXPLAIN RECONSTRUCT $nid MODALITY audio QUALITY high

-- Retorna:
-- ReconstructLatent

Informacoes mostradas no plano:

---

3.6 UNION / UNION ALL (NQL 3.0)

Combina resultados de duas ou mais queries em um unico resultado. UNION remove duplicatas; UNION ALL mantem todas as linhas.

Sintaxe:

<query1>
UNION [ALL]
<query2>

Exemplos:

-- Combinar Semantic e Episodic de alta energia (sem duplicatas)
MATCH (n:Semantic) WHERE n.energy > 0.8 RETURN n LIMIT 10
UNION
MATCH (n:Episodic) WHERE n.energy > 0.9 RETURN n LIMIT 10

-- Manter todas as linhas (com duplicatas)
MATCH (n) WHERE n.energy > 0.9 RETURN n LIMIT 5
UNION ALL
MATCH (n) WHERE n.depth < 0.2 RETURN n LIMIT 5

---

3.7 UNWIND (NQL 3.0)

Expande uma lista em linhas individuais. Util para iterar sobre arrays de valores.

Sintaxe:

UNWIND expressao AS alias
RETURN alias

Exemplos:

-- Expandir lista literal
UNWIND [1, 2, 3, 4, 5] AS x
RETURN x

-- Expandir lista de strings
UNWIND ["Memory", "Concept", "Episodic"] AS tipo
RETURN tipo

---

3.8 SHORTEST_PATH (NQL 3.0)

Encontra o caminho mais curto entre dois padroes de nos no grafo.

Sintaxe:

SHORTEST_PATH (a[:Label])-[*[..n]]->(b[:Label])
[LIMIT n]

Exemplos:

-- Caminho mais curto entre Concept e Memory (max 5 hops)
SHORTEST_PATH (a:Concept)-[*..5]->(b:Memory) LIMIT 1

-- Caminho entre quaisquer dois nos
SHORTEST_PATH (a)-[*..10]->(b) LIMIT 3

---

3.9 MATCH ELITES (NQL 3.0)

Retorna os nos com maior energia no grafo — os "Ubermenschen" do NietzscheDB.

Sintaxe:

MATCH ELITES [LIMIT n]

Exemplos:

-- Top 10 nos de elite
MATCH ELITES LIMIT 10

-- Top 50
MATCH ELITES LIMIT 50

Implementacao: Usa scan completo com ordenacao por energia decrescente.

---

3.10 MEASURE TENSION / MEASURE TGC (NQL 3.0)

Metricas de saude do grafo.

MEASURE TENSION — calcula a tensao hiperbolica entre dois padroes de nos:

MEASURE TENSION (a[:Label]), (b[:Label])

MEASURE TGC — calcula a Topological Generative Capacity do grafo:

MEASURE TGC

Exemplos:

-- Tensao entre conceitos e memorias
MEASURE TENSION (a:Concept), (b:Memory)

-- TGC global
MEASURE TGC

TGC = intensity x mean_quality x (1 + alpha x deltaH_s) x (1 + beta x deltaE_g) Veja documentacao detalhada em docs/articles/NietzscheDB-Topological-Generative-Capacity.md.

---

3.11 FIND NEAREST (NQL 3.0)

Busca k-NN (nearest neighbors) no espaco hiperbolico com namespace opcional.

Sintaxe:

FIND NEAREST ["namespace"] TARGET expressao [LIMIT n]

Exemplos:

-- Buscar 5 nos mais proximos de um vetor
FIND NEAREST TARGET $query_vec LIMIT 5

-- Buscar em namespace especifico
FIND NEAREST "medical" TARGET $query_vec LIMIT 10

---

4. Operadores de Distancia

4.1 HYPERBOLIC_DIST

Calcula a distancia geodesica entre o embedding de um no e um vetor de query na Bola de Poincare.

HYPERBOLIC_DIST(alias.embedding, $param | [v1, v2, ...]) -> Float

Formula:

d(u,v) = arcosh(1 + 2||u-v||^2 / ((1-||u||^2)(1-||v||^2)))

Usos:

-- Em WHERE
WHERE HYPERBOLIC_DIST(m.embedding, $query_vec) < 0.5

-- Em ORDER BY
ORDER BY HYPERBOLIC_DIST(m.embedding, $query_vec) ASC

-- Com vetor inline
WHERE HYPERBOLIC_DIST(n.embedding, [0.1, 0.2, 0.0]) < 0.3

Interpretacao dos valores:

Importante: distancia hiperbolica nao e comparavel com distancia euclidiana (cosine). Um threshold de 0.5 em NQL e completamente diferente de similarity > 0.5 em bancos euclidianos.

---

4.2 SENSORY_DIST (Fase 11)

Distancia entre o latent sensorial de um no e um vetor de query. Opera no espaco latente hiperbolico dos encoders sensoriais.

SENSORY_DIST(alias.field, $param) -> Float

-- Em WHERE
WHERE SENSORY_DIST(n.latent, $q) < 0.3

-- Em ORDER BY
ORDER BY SENSORY_DIST(n.latent, $q) ASC

-- Buscar sessoes de voz com prosodia similar
MATCH (s:SessionMemory)
WHERE SENSORY_DIST(s.latent, $audio_sample) < 0.4
RETURN s
ORDER BY SENSORY_DIST(s.latent, $audio_sample) ASC
LIMIT 10

---

5. Funcoes Matematicas Eponymous

NQL introduz 13 funcoes geometricas built-in nomeadas em homenagem aos matematicos cujo trabalho fundamenta a geometria hiperbolica, a difusao espectral e a teoria de grafos do NietzscheDB. NQL 3.0 adiciona mais 5 funcoes cognitivas nomeadas em homenagem a fisicos e matematicos (ver secao 6).

Estas funcoes operam diretamente sobre nos e seus embeddings, arestas e vizinhancas, sem necessidade de exportar dados para ferramentas externas.

Categorias de assinatura

---

5.1 POINCARE_DIST — Henri Poincare

Distancia geodesica no modelo da Bola de Poincare. Alias funcional para HYPERBOLIC_DIST, mas usando a convencao eponymous.

POINCARE_DIST(alias.embedding, $param | [v1, v2, ...]) -> Float

Formula:

d(u,v) = arcosh(1 + 2||u-v||^2 / ((1-||u||^2)(1-||v||^2)))

MATCH (n)
WHERE POINCARE_DIST(n.embedding, $q) < 0.5
RETURN n
ORDER BY POINCARE_DIST(n.embedding, $q) ASC
LIMIT 10

---

5.2 KLEIN_DIST — Felix Klein

Distancia geodesica no modelo de Beltrami-Klein. Computa a mesma geodesica que Poincare, mas via coordenadas de Klein.

KLEIN_DIST(alias.embedding, $param | [v1, v2, ...]) -> Float

Transformacao Poincare -> Klein:

k = 2p / (1 + ||p||^2)

Distancia de Klein:

d_K = acosh((1 - k1.k2) / sqrt((1 - ||k1||^2)(1 - ||k2||^2)))

MATCH (n)
WHERE KLEIN_DIST(n.embedding, $q) < 0.5
RETURN n
ORDER BY KLEIN_DIST(n.embedding, $q) ASC
LIMIT 10

-- Com vetor inline
MATCH (n)
WHERE KLEIN_DIST(n.embedding, [0.1, 0.2]) < 1.0
RETURN n

Quando usar Klein vs Poincare: Klein preserva geodesicas como linhas retas — util para interpolacao e visualizacao. Poincare preserva angulos (conformal) — melhor para kNN e clustering.

---

5.3 MINKOWSKI_NORM — Hermann Minkowski

Fator conformal lambda = 2/(1-||x||^2) no ponto do no. Mede o quanto o espaco esta "esticado" naquela posicao. Valores maiores indicam nos mais proximos da fronteira (mais profundos na hierarquia).

MINKOWSKI_NORM(alias.embedding) -> Float

Formula:

lambda(x) = 2 / (1 - ||x||^2)

-- Encontrar nos profundos na hierarquia (proximos da fronteira)
MATCH (n)
WHERE MINKOWSKI_NORM(n.embedding) > 5.0
RETURN n
ORDER BY MINKOWSKI_NORM(n.embedding) DESC
LIMIT 10

Interpretacao:

---

5.4 LOBACHEVSKY_ANGLE — Nikolai Lobachevsky

Angulo de paralelismo de Lobachevsky: a relacao fundamental entre distancia e angulo em geometria hiperbolica.

LOBACHEVSKY_ANGLE(alias.embedding, $param | [vec]) -> Float  (radianos)

Formula:

Pi(d) = 2 * arctan(e^(-d))

Onde d e a distancia hiperbolica entre o no e o vetor de query.

-- Angulo de paralelismo entre no e ponto de referencia
MATCH (n)
WHERE LOBACHEVSKY_ANGLE(n.embedding, $q) < 0.8
RETURN n

Interpretacao:

• Pi(d) -> pi/2 quando d -> 0 (espaco localmente euclidiano)
• Pi(d) -> 0 quando d -> infinito (curvatura domina)

---

5.5 RIEMANN_CURVATURE — Bernhard Riemann

Estimativa discreta da curvatura de Ollivier-Ricci local. Mede o quanto a vizinhanca de um no e "curva" comparando distancia de embedding com distancia de grafo.

RIEMANN_CURVATURE(alias) -> Float

Formula:

kappa = 1 - (media_dist_embedding_vizinhos)

Onde a media e sobre todos os vizinhos de saida do no.

-- Encontrar nos em regioes de alta curvatura
MATCH (n)
WHERE RIEMANN_CURVATURE(n) > 0.5
RETURN n

-- Nos em regioes planas (curvatura ~0)
MATCH (n)
WHERE RIEMANN_CURVATURE(n) BETWEEN -0.1 AND 0.1
RETURN n

Interpretacao:

Requer adjacencia: Esta funcao acessa a estrutura de vizinhanca do grafo. Nos isolados retornam 0.0.

---

5.6 GAUSS_KERNEL — Carl Friedrich Gauss

Heat kernel gaussiano no grafo: exp(-d^2/(4t)). Conecta-se diretamente ao operador DIFFUSE — e a funcao de transferencia do calor no tempo t.

GAUSS_KERNEL(alias, t) -> Float     -- t = escalar ou $param

Formula:

h_t(x) = exp(-||x||^2 / (4t))

Onde ||x|| e a norma euclidiana do embedding (distancia do centro).

-- Encontrar nos com alta resposta ao kernel em t=0.5
MATCH (n)
WHERE GAUSS_KERNEL(n, 0.5) > 0.8
RETURN n

-- Com parametro
MATCH (n)
WHERE GAUSS_KERNEL(n, $t) > $threshold
RETURN n
ORDER BY GAUSS_KERNEL(n, $t) DESC
LIMIT 20

Interpretacao:

• t pequeno -> kernel decai rapido -> so nos proximos do centro respondem
• t grande -> kernel decai devagar -> todos os nos respondem

---

5.7 CHEBYSHEV_COEFF — Pafnuty Chebyshev

Polinomio de Chebyshev T_k(x) avaliado na posicao normalizada do no. Fundamental para filtros espectrais em grafos — base dos GNNs espectrais.

CHEBYSHEV_COEFF(alias, k) -> Float     -- k = ordem do polinomio

Formula:

x = 2 * ||embedding|| - 1     (normalizado para [-1, 1])
T_k(x) = cos(k * arccos(x))

-- T_0(x) = 1 para qualquer x (componente DC)
MATCH (n)
WHERE CHEBYSHEV_COEFF(n, 0) > 0.9
RETURN n

-- T_1(x) = x (componente linear)
MATCH (n)
WHERE CHEBYSHEV_COEFF(n, 1) > 0.5
RETURN n

-- T_3 para filtro de alta frequencia
MATCH (n)
WHERE CHEBYSHEV_COEFF(n, 3) > 0.5
RETURN n

Propriedades uteis:

• T_0(x) = 1 sempre
• T_1(x) = x
• |T_k(x)| <= 1 para x in [-1, 1]
• Oscila mais rapido com k maior -> captura detalhes de alta frequencia

---

5.8 RAMANUJAN_EXPANSION — Srinivasa Ramanujan

Razao de expansao local baseada no bound de Ramanujan para grafos expansores. Mede o quanto um no se comporta como parte de um grafo expansor.

RAMANUJAN_EXPANSION(alias) -> Float

Formula:

bound = 2 * sqrt(deg - 1)    (bound de Ramanujan para grafos d-regulares)
expansion = deg / bound

Onde deg e o grau total (in + out) do no.

-- Nos com boa propriedade de expansao
MATCH (n)
WHERE RAMANUJAN_EXPANSION(n) > 1.0
RETURN n

-- Nos potencialmente bottleneck (baixa expansao)
MATCH (n)
WHERE RAMANUJAN_EXPANSION(n) < 0.5
  AND LAPLACIAN_SCORE(n) > 2.0
RETURN n

Interpretacao:

Requer adjacencia: Nos isolados (grau total <= 1) retornam 0.0.

---

5.9 HAUSDORFF_DIM — Felix Hausdorff

Dimensao de Hausdorff local do no. Mede a complexidade fractal da vizinhanca. Retorna o valor pre-calculado hausdorff_local do no.

HAUSDORFF_DIM(alias) -> Float   (range tipico: 0.0-2.0)

-- Filtrar nos no regime fractal saudavel
MATCH (n)
WHERE HAUSDORFF_DIM(n) BETWEEN 1.2 AND 1.8
RETURN n

-- Nos candidatos a poda
MATCH (n)
WHERE HAUSDORFF_DIM(n) < 0.5
RETURN n

Interpretacao:

---

5.10 EULER_CHAR — Leonhard Euler

Caracteristica de Euler local: chi = V - E para o ego-grafo de 1 hop do no. Mede a "forma topologica" da vizinhanca imediata.

EULER_CHAR(alias) -> Float

Formula:

V = 1 + |vizinhos|           (no + seus vizinhos)
E = |arestas no ego-grafo|   (arestas do no + entre vizinhos)
chi = V - E

-- No isolado: chi = 1 (V=1, E=0)
MATCH (n)
WHERE EULER_CHAR(n) = 1
RETURN n

-- Vizinhanca com muitas conexoes (chi negativo)
MATCH (n)
WHERE EULER_CHAR(n) < 0
RETURN n

Interpretacao:

• chi = 1 -> no isolado
• chi > 0 -> vizinhanca tipo arvore (poucos ciclos)
• chi = 0 -> equilibrio (como um toro)
• chi < 0 -> vizinhanca densa, muitos ciclos

Requer adjacencia: Conta arestas entre vizinhos no ego-grafo.

---

5.11 LAPLACIAN_SCORE — Pierre-Simon Laplace

Score do Laplaciano do grafo: diagonal L_ii = grau(i). Para grafos nao-ponderados, e simplesmente o grau total do no.

LAPLACIAN_SCORE(alias) -> Float

Formula:

L_ii = deg_out(i) + deg_in(i)

-- Nos com alto grau (hubs)
MATCH (n)
WHERE LAPLACIAN_SCORE(n) > 10
RETURN n
ORDER BY LAPLACIAN_SCORE(n) DESC
LIMIT 20

-- Nos folha
MATCH (n)
WHERE LAPLACIAN_SCORE(n) = 1
RETURN n

Conexao com teoria espectral: O Laplaciano do grafo L = D - A controla a difusao. Autovalores de L determinam a velocidade de convergencia do DIFFUSE.

---

5.12 FOURIER_COEFF — Joseph Fourier

Coeficiente de Fourier no grafo: cos(k * pi * x) onde x e a posicao normalizada do no. Base para analise espectral no grafo.

FOURIER_COEFF(alias, k) -> Float     -- k = numero de onda

Formula:

coeff = cos(k * pi * ||embedding||)

-- Componente fundamental (k=1)
MATCH (n)
WHERE FOURIER_COEFF(n, 1) > 0.5
RETURN n

-- Harmonica superior (k=3)
MATCH (n)
WHERE FOURIER_COEFF(n, 3) > 0.0
RETURN n
ORDER BY FOURIER_COEFF(n, 3) DESC

---

5.13 DIRICHLET_ENERGY — Peter Gustav Lejeune Dirichlet

Energia de Dirichlet local: soma dos quadrados das diferencas de energia entre o no e seus vizinhos. Mede a "rugosidade" do campo de energia na vizinhanca.

DIRICHLET_ENERGY(alias) -> Float

Formula:

E(i) = sum_{j in N(i)} (energy(i) - energy(j))^2

-- Nos com alta variacao de energia na vizinhanca
MATCH (n)
WHERE DIRICHLET_ENERGY(n) > 0.5
RETURN n
ORDER BY DIRICHLET_ENERGY(n) DESC

-- Nos em vizinhanca homogenea (baixa energia de Dirichlet)
MATCH (n)
WHERE DIRICHLET_ENERGY(n) < 0.01
RETURN n

Interpretacao:

• E = 0 -> todos os vizinhos tem mesma energia (suave)
• E pequeno -> vizinhanca homogenea
• E grande -> fronteira entre regioes de alta e baixa energia

Requer adjacencia e storage: Acessa a energia dos vizinhos via grafo.

---

6. Funcoes Cognitivas Eponymous (NQL 3.0)

NQL 3.0 introduz 5 funcoes cognitivas nomeadas em homenagem a fisicos e matematicos cujo trabalho fundamenta a dinamica do NietzscheDB — continuando a tradicao das 13 funcoes geometricas eponymous.

6.1 BOLTZMANN_SURVIVAL — Ludwig Boltzmann

Probabilidade de sobrevivencia do no baseada em estatistica de energia (distribuicao de Boltzmann).

BOLTZMANN_SURVIVAL(alias) -> Float   (0.0-1.0)

-- Nos com alta probabilidade de sobrevivencia
MATCH (n)
WHERE BOLTZMANN_SURVIVAL(n) > 0.7
RETURN n, BOLTZMANN_SURVIVAL(n) AS survival
ORDER BY survival DESC LIMIT 20

-- Nos em risco de esquecimento
MATCH (n)
WHERE BOLTZMANN_SURVIVAL(n) < 0.3
RETURN n

---

6.2 HELMHOLTZ_GRADIENT — Hermann von Helmholtz

Gradiente de energia livre local. Mede a direcao e magnitude do fluxo de energia na vizinhanca.

HELMHOLTZ_GRADIENT(alias) -> Float

-- Nos com alto gradiente de energia (fronteiras entre regioes)
MATCH (n)
WHERE HELMHOLTZ_GRADIENT(n) > 0.5
RETURN n, HELMHOLTZ_GRADIENT(n) AS gradient
ORDER BY gradient DESC

-- Nos em equilibrio (gradiente ~0)
MATCH (n)
WHERE HELMHOLTZ_GRADIENT(n) < 0.05
RETURN n

---

6.3 LYAPUNOV_DELTA — Aleksandr Lyapunov

Divergencia de estabilidade entre dois nos. Mede o quanto as trajetorias de dois nos divergem no espaco hiperbolico.

LYAPUNOV_DELTA(alias1, alias2) -> Float

-- Pares de nos com baixa divergencia (estaveis)
MATCH (a:Concept), (b:Concept)
WHERE LYAPUNOV_DELTA(a, b) < 0.1
RETURN a, b, LYAPUNOV_DELTA(a, b) AS delta
LIMIT 20

-- Pares com alta divergencia (instabilidade)
MATCH (a), (b)
WHERE LYAPUNOV_DELTA(a, b) > 0.8
RETURN a, b
LIMIT 10

---

6.4 PRIGOGINE_BASIN — Ilya Prigogine

Profundidade do basin de estrutura dissipativa. Mede o quanto um no esta "preso" em um atrator.

PRIGOGINE_BASIN(alias) -> Float

-- Nos em bacias profundas (atratores fortes)
MATCH (n)
WHERE PRIGOGINE_BASIN(n) > 0.7
RETURN n, PRIGOGINE_BASIN(n) AS basin
ORDER BY basin DESC

-- Nos em bacias rasas (facilmente perturbados)
MATCH (n)
WHERE PRIGOGINE_BASIN(n) < 0.2
RETURN n

---

6.5 ERDOS_EDGE_PROB — Paul Erdos

Probabilidade de formacao de aresta entre dois nos pelo modelo Erdos-Renyi.

ERDOS_EDGE_PROB(alias1, alias2) -> Float   (0.0-1.0)

-- Pares com alta probabilidade de conexao
MATCH (a:Semantic), (b:Semantic)
WHERE ERDOS_EDGE_PROB(a, b) > 0.6
RETURN a, b, ERDOS_EDGE_PROB(a, b) AS prob
ORDER BY prob DESC LIMIT 20

-- Sugerir novas arestas
MATCH (a), (b)
WHERE ERDOS_EDGE_PROB(a, b) > 0.8
  AND NOT EXISTS { (a)-[]->(b) }
RETURN a, b
LIMIT 10

---

7. Funcoes Built-in (NQL 3.0)

NQL 3.0 adiciona 30+ funcoes built-in para manipulacao de strings, matematica, conversao de tipos e tratamento de nulos.

7.1 String

Exemplos:

-- Busca case-insensitive
MATCH (n) WHERE UPPER(n.title) = "NIETZSCHE" RETURN n

-- Manipulacao de strings no RETURN
MATCH (n)
RETURN n.title, LENGTH(n.title) AS len, REVERSE(n.title) AS rev
LIMIT 10

-- Substring
MATCH (n)
RETURN SUBSTRING(n.title, 0, 5) AS prefix
LIMIT 10

-- Replace
MATCH (n)
RETURN REPLACE(n.title, "old", "new") AS updated
LIMIT 10

-- Concat
MATCH (n)
RETURN CONCAT(n.node_type, ": ", n.title) AS full_label
LIMIT 10

7.2 Math

Exemplos:

-- Distancia absoluta de um alvo
MATCH (n)
RETURN n, ABS(n.energy - 0.5) AS dist_from_half
ORDER BY dist_from_half ASC LIMIT 10

-- Arredondamento
MATCH (n)
RETURN ROUND(n.depth) AS rounded_depth, CEIL(n.energy * 10) AS energy_decile

-- Raiz quadrada e potencia
MATCH (n) WHERE SQRT(n.energy) > 0.7 RETURN n
MATCH (n) RETURN POW(n.energy, 2) AS energy_sq

7.3 Cast

Exemplos:

-- Converter para string
MATCH (n)
RETURN TO_STRING(n.energy) AS energy_str

-- Converter para inteiro (porcentagem)
MATCH (n)
RETURN TO_INT(n.energy * 100) AS energy_pct

-- Converter para float
MATCH (n)
RETURN TO_FLOAT(n.lsystem_generation) AS gen_float

7.4 Null

Exemplo:

-- Fallback encadeado
MATCH (n)
RETURN COALESCE(n.title, n.name, n.id) AS label
LIMIT 20

---

8. Condicoes Avancadas (NQL 3.0)

8.1 IS NULL / IS NOT NULL

Verifica se uma propriedade e nula (nao definida no no).

-- Nos sem titulo
MATCH (n) WHERE n.title IS NULL RETURN n LIMIT 10

-- Nos com titulo definido
MATCH (n) WHERE n.title IS NOT NULL RETURN n LIMIT 20

-- Combinado com outras condicoes
MATCH (n)
WHERE n.energy > 0.5 AND n.expires_at IS NULL
RETURN n

Semantica NULL: Campos nao definidos no content do no sao tratados como NULL. Comparacoes com NULL seguem semantica SQL — NULL > 0.5 retorna false.

8.2 Regex (=~)

Comparacao por expressao regular (Rust regex syntax).

-- Titulo que comeca com "neuro"
MATCH (n) WHERE n.title =~ "^neuro.*" RETURN n LIMIT 10

-- Contendo digitos
MATCH (n) WHERE n.id =~ "\\d+" RETURN n LIMIT 10

-- Case-insensitive com flag inline
MATCH (n) WHERE n.title =~ "(?i)memory" RETURN n LIMIT 20

Motor de regex: Usa a crate regex do Rust — sintaxe completa em https://docs.rs/regex. Patterns invalidos retornam false silenciosamente.

8.3 EXISTS subquery

Verifica se um padrao de grafo existe para o no atual.

-- Nos que tem pelo menos uma aresta de saida
MATCH (n) WHERE EXISTS { (n)-[:Association]->(m) } RETURN n

-- Nos sem filhos hierarquicos
MATCH (n) WHERE NOT EXISTS { (n)-[:Hierarchical]->(child) } RETURN n

-- Combinado com filtros
MATCH (n)
WHERE n.energy > 0.5
  AND EXISTS { (n)-[:Association]->(m) WHERE m.energy > 0.3 }
RETURN n

Performance: EXISTS faz scan do grafo para cada no candidato. Use com LIMIT para evitar queries custosas.

8.4 CASE WHEN

Expressao condicional que retorna valores diferentes baseado em condicoes.

-- Classificar nos por nivel de energia
MATCH (n)
RETURN n,
  CASE WHEN n.energy > 0.8 THEN "elite"
       WHEN n.energy > 0.5 THEN "ativo"
       WHEN n.energy > 0.2 THEN "decaindo"
       ELSE "moribundo" END AS status
LIMIT 20

-- Em WHERE
MATCH (n)
WHERE CASE WHEN n.node_type = "Semantic" THEN n.energy > 0.3
           ELSE n.energy > 0.7 END
RETURN n

-- Em ORDER BY
MATCH (n)
RETURN n
ORDER BY CASE WHEN n.node_type = "Concept" THEN 0
              WHEN n.node_type = "Semantic" THEN 1
              ELSE 2 END ASC
LIMIT 20

---

9. Clausulas e Operadores

9.1 WHERE

Filtros booleanos sobre nos, arestas e funcoes.

WHERE n.energy > 0.3
  AND (n.depth > 0.6 OR n.node_type = "Memory")
  AND NOT n.energy < 0.1

9.2 ORDER BY

Ordenacao por propriedade, funcao de distancia ou funcao matematica.

ORDER BY n.energy DESC
ORDER BY HYPERBOLIC_DIST(n.embedding, $q) ASC
ORDER BY POINCARE_DIST(n.embedding, $q) ASC
ORDER BY SENSORY_DIST(n.latent, $q) ASC

9.3 LIMIT / SKIP

LIMIT 10           -- maximo 10 resultados
SKIP 20            -- pular os primeiros 20
LIMIT 10 SKIP 20   -- paginacao: pagina 3 (20..30)

Nota: NQL usa SKIP (nao OFFSET). O SKIP e aplicado apos ORDER BY e antes de LIMIT.

9.4 RETURN

RETURN n                                           -- no completo
RETURN n.energy, n.depth                           -- campos especificos
RETURN COUNT(*) AS total                           -- agregacao
RETURN n.node_type, AVG(n.energy) AS avg_e         -- agregacao + campo
RETURN DISTINCT n                                  -- sem duplicatas

9.5 DISTINCT

Remove nos duplicados por ID no resultado.

RETURN DISTINCT n
RETURN DISTINCT n LIMIT 50

9.6 AS (alias)

Renomeia campos no resultado.

RETURN n.energy AS vitalidade
RETURN COUNT(*) AS total
RETURN AVG(n.energy) AS media_energia

9.7 IN

Verifica se um valor pertence a uma lista.

WHERE n.energy IN (0.3, 0.5, 0.8)
WHERE n.node_type IN ("Memory", "Concept")

9.8 BETWEEN

Verifica se um valor esta dentro de um intervalo (inclusivo).

WHERE n.energy BETWEEN 0.3 AND 0.8
WHERE n.depth BETWEEN 0.0 AND 0.5

Equivale a n.energy >= 0.3 AND n.energy <= 0.8 mas com sintaxe mais legivel.

9.9 CONTAINS / STARTS_WITH / ENDS_WITH

Operadores de busca em strings.

WHERE n.id CONTAINS "abc"
WHERE n.node_type STARTS_WITH "Mem"
WHERE n.id ENDS_WITH "f00"

9.10 AND / OR / NOT

Operadores logicos com precedencia: NOT > AND > OR. Parenteses podem alterar a precedencia.

WHERE n.energy > 0.3 AND n.depth < 0.8
WHERE n.energy > 0.9 OR n.depth < 0.1
WHERE NOT n.energy < 0.1
WHERE (n.energy > 0.5 OR n.depth < 0.3) AND NOT n.node_type = "Pruned"

Operadores de comparacao

---

10. Agregacoes

10.1 COUNT / SUM / AVG / MIN / MAX

NQL v2 suporta funcoes de agregacao completas.

-- Contar todos os nos
MATCH (n)
WHERE n.energy > 0.0
RETURN COUNT(*) AS total

-- Contar por propriedade
MATCH (n)
WHERE n.energy > 0.0
RETURN COUNT(n.energy) AS contagem

-- Media de energia
MATCH (n)
WHERE n.energy > 0.0
RETURN AVG(n.energy) AS media

-- Estatisticas completas
MATCH (n)
WHERE n.energy > 0.0
RETURN COUNT(*) AS total,
       AVG(n.energy) AS media,
       MIN(n.energy) AS minima,
       MAX(n.energy) AS maxima,
       SUM(n.energy) AS soma

10.2 COLLECT (NQL 3.0)

Agrega valores em um array JSON. Util para coletar todos os valores de um campo por grupo.

-- Coletar energias por tipo de no
MATCH (n)
WHERE n.energy > 0.0
RETURN n.node_type, COLLECT(n.energy) AS energias
GROUP BY n.node_type

-- Coletar IDs de nos de alta energia
MATCH (n)
WHERE n.energy > 0.7
RETURN COLLECT(n.id) AS elite_ids

Formato de saida: COLLECT retorna um array JSON como string: "[0.8, 0.9, 0.7]".

10.3 GROUP BY

Agrupa resultados por campo ou propriedade antes de aplicar agregacoes.

-- Contagem por tipo de no
MATCH (n)
WHERE n.energy > 0.0
RETURN n.node_type, COUNT(*) AS total
GROUP BY n.node_type

-- Media de energia por tipo
MATCH (n)
WHERE n.energy > 0.0
RETURN n.node_type, AVG(n.energy) AS media_e, COUNT(*) AS qtd
GROUP BY n.node_type

---

11. Planner

O Planner e o componente que decide como executar cada query. Nao ha hints manuais necessarios — o Planner escolhe automaticamente.

Estrategias disponiveis

NodeScan: varredura sequencial de nos com filtro. Ativado para qualquer MATCH (n) sem padrao de aresta.

-- -> NodeScan(label=Memory) -> Filter -> Sort -> Limit
MATCH (n:Memory)
WHERE n.energy > 0.3
RETURN n
ORDER BY n.energy DESC
LIMIT 10

EdgeScan: varredura de arestas com filtro. Ativado quando a query tem padrao de aresta.

-- -> EdgeScan(type=Association, dir=-->)
MATCH (a)-[:Association]->(b)
WHERE a.energy > 0.5
RETURN b

DiffusionPlan: usa o heat kernel hiperbolico. Ativado por qualquer statement DIFFUSE.

-- -> DiffusionWalk(max_hops=5, t_scales=3)
DIFFUSE FROM $node_id WITH t = [0.1, 1.0, 10.0] MAX_HOPS 5
RETURN path

ReconstructPlan: decodifica latent sensorial. Ativado por RECONSTRUCT.

Visualizar o plano

Use EXPLAIN para ver a estrategia escolhida:

EXPLAIN MATCH (n:Memory)
  WHERE n.energy > 0.3 AND n.depth < 0.8
  RETURN n
  ORDER BY n.energy DESC
  LIMIT 10
  SKIP 5

-- Saida:
-- NodeScan(label=Memory) -> Filter(conditions=1) -> Sort(dir=Desc) -> Skip(5) -> Limit(10)

---

12. Parametros e Variaveis

Tipos de parametros

Passagem de parametros (gRPC)

Parametros sao passados via o campo params da mensagem QueryRequest:

message QueryRequest {
  string nql = 1;
  map<string, QueryParamValue> params = 2;
}

Passagem de parametros (Rust SDK)

use nietzsche_query::{parse, execute, Params, ParamValue};

let query = parse("MATCH (n) WHERE POINCARE_DIST(n.embedding, $q) < 0.5 RETURN n LIMIT 10")?;

let mut params = Params::new();
params.insert("q".into(), ParamValue::Vector(vec![0.1, 0.2, 0.0, 0.0]));

let results = execute(&query, &storage, &adjacency, &params)?;

---

13. Comparacao com outras linguagens

NQL vs Cypher (Neo4j)

NQL vs SQL

---

14. Exemplos por Dominio

EVA-Mind — Saude e Memoria Clinica

Buscar memorias por proximidade hiperbolica com funcao eponymous:

MATCH (m:Memory)
WHERE POINCARE_DIST(m.embedding, $context_vec) < 0.5
  AND m.energy > 0.3
RETURN m
ORDER BY POINCARE_DIST(m.embedding, $context_vec) ASC
LIMIT 15

Analisar curvatura local para detectar clusters de conhecimento:

MATCH (n)
WHERE RIEMANN_CURVATURE(n) > 0.5
  AND n.energy > 0.5
RETURN n, RIEMANN_CURVATURE(n) AS curvatura
ORDER BY curvatura DESC
LIMIT 20

Encontrar hubs de conhecimento via Laplaciano:

MATCH (n)
WHERE LAPLACIAN_SCORE(n) > 10
RETURN n, LAPLACIAN_SCORE(n) AS grau
ORDER BY grau DESC
LIMIT 10

Detectar fronteiras semanticas via Dirichlet:

MATCH (n)
WHERE DIRICHLET_ENERGY(n) > 0.5
  AND n.energy > 0.3
RETURN n, DIRICHLET_ENERGY(n) AS borda
ORDER BY borda DESC
LIMIT 20

Diagnosticar saude fractal do grafo:

MATCH (n)
WHERE n.energy > 0.0
RETURN AVG(n.hausdorff_local) AS dim_media,
       MIN(n.hausdorff_local) AS dim_min,
       MAX(n.hausdorff_local) AS dim_max,
       COUNT(*) AS total_nos

Ativar rede de memorias associadas:

DIFFUSE FROM $diagnosis_node
  WITH t = [0.5, 2.0, 8.0]
  MAX_HOPS 5
RETURN path

Reconstruir sessao de voz:

RECONSTRUCT $session_node_id
  MODALITY audio
  QUALITY high

Buscar sessoes com prosodia similar:

MATCH (s:SessionMemory)
WHERE SENSORY_DIST(s.latent, $audio_sample) < 0.35
RETURN s
ORDER BY SENSORY_DIST(s.latent, $audio_sample) ASC
LIMIT 5

Estatisticas por tipo de no:

MATCH (n)
WHERE n.energy > 0.0
RETURN n.node_type, COUNT(*) AS total, AVG(n.energy) AS media
GROUP BY n.node_type

---

Analise Espectral e Geometrica

Filtro espectral de Chebyshev — selecionar nos por frequencia:

-- Componente de baixa frequencia (k=1)
MATCH (n)
WHERE CHEBYSHEV_COEFF(n, 1) > 0.5
  AND n.energy > 0.3
RETURN n

-- Componente de alta frequencia (k=5)
MATCH (n)
WHERE CHEBYSHEV_COEFF(n, 5) > 0.3
RETURN n

Heat kernel gaussiano — simular difusao pontual:

MATCH (n)
WHERE GAUSS_KERNEL(n, 0.5) > 0.5
RETURN n, GAUSS_KERNEL(n, 0.5) AS kernel_val
ORDER BY kernel_val DESC
LIMIT 20

Identificar expansores locais (Ramanujan):

MATCH (n)
WHERE RAMANUJAN_EXPANSION(n) > 1.0
RETURN n, RAMANUJAN_EXPANSION(n) AS expansion
ORDER BY expansion DESC

Analise topologica (Euler):

-- Nos com vizinhanca tipo arvore
MATCH (n)
WHERE EULER_CHAR(n) > 0
  AND LAPLACIAN_SCORE(n) > 3
RETURN n, EULER_CHAR(n) AS chi, LAPLACIAN_SCORE(n) AS grau

-- Nos em vizinhanca densa
MATCH (n)
WHERE EULER_CHAR(n) < -2
RETURN n

Coeficientes de Fourier no grafo:

MATCH (n)
WHERE FOURIER_COEFF(n, 1) > 0.5
RETURN n, FOURIER_COEFF(n, 1) AS f1, FOURIER_COEFF(n, 3) AS f3

Profundidade via Minkowski — hierarquia no espaco:

MATCH (n)
WHERE MINKOWSKI_NORM(n.embedding) > 5.0
RETURN n, MINKOWSKI_NORM(n.embedding) AS profundidade
ORDER BY profundidade DESC
LIMIT 10

Distancia de Klein com vetor inline:

MATCH (n)
WHERE KLEIN_DIST(n.embedding, [0.1, 0.2, 0.0, 0.0]) < 0.5
RETURN n
ORDER BY KLEIN_DIST(n.embedding, [0.1, 0.2, 0.0, 0.0]) ASC
LIMIT 10

---

15. Erros e Diagnostico

Erros estruturados (NQL v2)

Exemplos de erro

Error: Parse("expected 'MATCH', 'DIFFUSE', 'RECONSTRUCT', or 'EXPLAIN'")

Error: UnknownAlias { alias: "x" }
  hint: defina o alias no padrao MATCH, ex: MATCH (x)

Error: ParamNotFound { name: "q" }
  hint: passe o parametro via params map

Error: ParamTypeMismatch { name: "q", expected: "Vector", got: "other" }
  hint: use ParamValue::Vector(vec![...])

---

16. Referencia Rapida

Statements

Operadores de distancia

Funcoes geometricas eponymous

Funcoes cognitivas eponymous (NQL 3.0)

Funcoes built-in (NQL 3.0)

Agregacoes

Clausulas e Operadores

Parametros DIFFUSE

Parametros RECONSTRUCT

---

Gramatica PEG (nql.pest)

A gramatica completa esta em crates/nietzsche-query/src/nql.pest.

Hierarquia de precedencia de condicoes:

NOT  >  AND  >  OR

Queries suportadas:

query = { SOI ~ (explain_query | reconstruct_query | diffuse_query
                | union_query | unwind_query | shortest_path_query
                | match_elites_query | measure_tension_query
                | measure_tgc_query | find_nearest_query
                | match_query) ~ EOI }

---

Notas finais

17. NQL 3.1: PostgreSQL-inspired Features

NQL 3.1 adiciona 10 features inspiradas no PostgreSQL, adaptadas ao paradigma hiperbolico do NietzscheDB.

17.1 CTEs (WITH ... AS)

Common Table Expressions permitem composicao de queries nomeadas.

-- CTE simples
WITH active AS (
  MATCH (n:Memory) WHERE n.energy > 0.5 RETURN n
)
MATCH (a) WHERE a.energy > 0.1 RETURN a

-- CTEs multiplos
WITH hot AS (
  MATCH (n) WHERE n.energy > 0.8 RETURN n
),
cold AS (
  MATCH (m) WHERE m.energy < 0.2 RETURN m
)
MATCH (a) RETURN a

17.2 Window Functions

Funcoes de janela para ranking e analytics sem colapsar linhas.

-- ROW_NUMBER: numeracao sequencial
MATCH (n:Memory)
RETURN n.name, ROW_NUMBER() OVER (ORDER BY n.energy DESC) AS rank

-- RANK com PARTITION BY: ranking dentro de grupos
MATCH (n:Memory)
RETURN n.name, n.label,
  RANK() OVER (PARTITION BY n.label ORDER BY n.energy DESC) AS rank_in_group

-- DENSE_RANK: sem gaps no ranking
MATCH (n)
RETURN n.name, DENSE_RANK() OVER (ORDER BY n.energy DESC) AS dense_rank

-- NTILE: distribuir em N buckets
MATCH (n)
RETURN n.name, NTILE(4) OVER (ORDER BY n.energy DESC) AS quartile

-- LAG/LEAD: acessar linha anterior/seguinte
MATCH (n)
RETURN n.name, LAG(n.energy) OVER (ORDER BY n.created_at ASC) AS prev_energy

Funcoes suportadas:

17.3 Views

Queries nomeadas reutilizaveis armazenadas no catalogo.

-- Criar uma view
CREATE VIEW high_energy AS
  MATCH (n) WHERE n.energy > 0.8 RETURN n

-- Remover uma view
DROP VIEW high_energy

17.4 Materialized Views

Views pre-computadas e cacheadas. Ideal para dashboards e queries pesadas.

-- Criar uma materialized view
CREATE MATERIALIZED VIEW top_nodes AS
  MATCH (n) RETURN n ORDER BY n.energy DESC LIMIT 100

-- Recomputar (refresh)
REFRESH MATERIALIZED VIEW top_nodes

-- Remover
DROP MATERIALIZED VIEW top_nodes

17.5 RETURNING Clause

Retorna dados das rows afetadas por mutacoes, evitando um segundo roundtrip.

-- CREATE com RETURNING
CREATE (n:Memory {title: "hello", energy: 0.9}) RETURNING n.id, n.created_at

-- DELETE com RETURN (dados dos nos deletados)
MATCH (n) WHERE n.energy < 0.01 DELETE n RETURN n.id, n.title

17.6 CHECK Constraints

Constraints arbitrarias sobre campos, validadas em cada insercao/update.

-- Adicionar constraint
ALTER COLLECTION memories ADD CONSTRAINT energy_range
  CHECK (n.energy >= 0.0)

ALTER COLLECTION memories ADD CONSTRAINT energy_max
  CHECK (n.energy <= 1.0)

-- Remover constraint
ALTER COLLECTION memories DROP CONSTRAINT energy_range

17.7 UNIQUE Indexes

Prevenir duplicatas a nivel de storage.

-- Criar indice unico
CREATE UNIQUE INDEX idx_email ON users (content.email)

-- Criar indice unico composto
CREATE UNIQUE INDEX idx_name_type ON memories (content.name, content.type)

-- Remover indice
DROP INDEX idx_email

17.8 Prepared Statements

Cache do plano de execucao para queries frequentes.

-- Preparar statement com tipos de parametros
PREPARE find_hot(float) AS
  MATCH (n) WHERE n.energy > $1 RETURN n

-- Executar com argumentos
EXECUTE find_hot(0.7)

-- Liberar
DEALLOCATE find_hot

17.9 LATERAL Subquery

Subquery correlacionada que referencia colunas da query externa. Ideal para "top-N por grupo".

-- Para cada Memory, buscar os 3 vizinhos mais energeticos
MATCH (n:Memory)
  LATERAL (MATCH (m) WHERE m.energy > 0.5 RETURN m LIMIT 3) AS top3
RETURN n, top3

17.10 Table Partitioning

Particionar collections para melhor performance em datasets grandes.

-- Particionar por range (ex: data de criacao)
ALTER COLLECTION logs PARTITION BY RANGE (created_at)

-- Particionar por lista (ex: regiao)
ALTER COLLECTION users PARTITION BY LIST (region)

-- Particionar por hash (ex: distribuir em 8 buckets)
ALTER COLLECTION events PARTITION BY HASH (id, 8)

Estrategias:

---

NQL v3.1 e a primeira linguagem de query de banco de dados que:

1. Opera nativamente em espaco hiperbolico — nao e um plugin ou extensao
2. Nomeia suas funcoes em homenagem a matematicos e fisicos que fundamentam cada operacao (18 funcoes eponymous: Poincare, Klein, Minkowski, Lobachevsky, Riemann, Gauss, Chebyshev, Ramanujan, Hausdorff, Euler, Laplace, Fourier, Dirichlet, Boltzmann, Helmholtz, Lyapunov, Prigogine, Erdos)
3. Integra analise espectral (Chebyshev, Fourier, Laplacian) diretamente na linguagem de query
4. Mede curvatura, topologia e expansao como primitivas de primeira classe
5. Reconstroi experiencias sensoriais a partir de latents comprimidos
6. Fecha o gap com Cypher/GQL com OPTIONAL MATCH, UNION, CASE WHEN, IS NULL, regex, EXISTS, UNWIND, SHORTEST_PATH, COLLECT, 30+ funcoes built-in — mantendo primitivas hiperbolicas unicas
7. Funcoes cognitivas fisico-nomeadas para analise de dinamica do grafo: sobrevivencia (Boltzmann), gradiente de energia (Helmholtz), divergencia (Lyapunov), bacias dissipativas (Prigogine), probabilidade de arestas (Erdos)
8. PostgreSQL-grade analytics — CTEs, Window Functions (ROW_NUMBER, RANK, DENSE_RANK, NTILE, LAG, LEAD), Views, Materialized Views, RETURNING clause, CHECK constraints, UNIQUE indexes, Prepared Statements, LATERAL subqueries, e Table Partitioning

github.com/JoseRFJuniorLLMs/NietzscheDB
AGPL-3.0 -- Jose R F Junior -- 2026