ORM, database, api e query builder

O NEO expõe APIs de alto nível para acesso a dados. A escolha entre Document, neo.db.*, Query Builder e SQL deve considerar regra de negócio, performance e o consumidor final do dado.

Quando usar Document e quando usar neo.db

Document

Use quando o fluxo precisa de eventos, validações e persistência completa.

neo.db

Use quando a necessidade é consulta, atualização pontual ou apoio a relatórios e páginas.

neo.db.get_list

Aplica permissões do usuário atual.

tasks = neo.db.get_list(
    "Task",
    filters={"status": "Open"},
    fields=["name", "subject", "date"],
    order_by="date desc",
    page_length=20
)

neo.db.get_all

Ignora permissões e exige cuidado.

all_tasks = neo.db.get_all("Task", fields=["name", "owner"])

neo.db.get_value

email = neo.db.get_value("User", "Administrator", "email")
title, status = neo.db.get_value("Task", "TASK-0001", ["title", "status"])

Outros recursos úteis

Recurso	Aplicação
neo.db.exists	Verifica existência
neo.db.set_value	Atualiza campo(s) diretamente
neo.db.count	Conta registros
neo.db.sql	SQL explícito
pluck	Busca uma coluna só

Exemplo de endpoint para front-end

import neo

@neo.whitelist()
def get_active_members():
    return neo.db.get_list(
        "Library Member",
        filters={"status": "Active"},
        fields=["name", "full_name", "email"],
        order_by="modified desc",
        page_length=50
    )

Cliente:

neo.call({
    method: "biblioteca.api.get_active_members",
    callback(r) {
        console.log(r.message);
    }
});

Performance em consultas

• selecione apenas os campos necessários;

• evite get_doc em loop;

• use paginação;

• crie índices coerentes;

• mova agregações pesadas para reports ou jobs.

Relação com ListView, reports e pages

Grande parte da experiência do front-end depende de consulta bem modelada:

• ListView precisa de filtros rápidos;

• pages precisam de payload previsível;

• portal precisa respeitar permissões;

• reports dependem de leitura eficiente.

Heurística prática

• comportamento completo do documento: Document;

• lista respeitando permissão: get_list;

• consulta interna ampla: get_all;

• leitura pontual: get_value;

• casos avançados: Query Builder ou SQL.