PT EN
Back to site

Managing Contexts

Each data domain in your operation — court cases, company registries, a legal code — lives in its own context, with its graph, its search indices, its prompts and its rules. Instead of filing a request for the infrastructure team to create databases, you create, edit, update, clear, delete and govern every context from a single screen: SistemaContextos (screens/settings-contextos.html). These are the platform's context databases (processos, cnpj, cpc…) — always created through the interface, never by the automated setup.

What you see on the screen

Top to bottom:

  1. Header — the "Contextos" title on the left and, in the top-right corner, the + Novo Contexto button, which opens the "Adicionar Novo Contexto Legal" form. The header reflows on its own for narrow screens.
  2. Context Visibility Matrix — the governance of where each context may be used (summary below).
  3. Per-context settings — a card with the same width as the Visibility Matrix, holding a vertical-list selector with one row per context (the active one is highlighted), matching the matrix row design; the list shows up to 8 contexts and grows a vertical scrollbar past that. Below it sits the action bar, which always operates on the active context of the selector:
ActionWhat it does
EditarOpens the "Editar Contexto — {context}" form. The button label is lean (just "Editar", without repeating the name) because the action follows the active context of the selector.
AtualizarOpens the context update modal: Atualizar agora and Agendar from the data source URL saved on it, with the progress bar and the scheduled updates; and, as secondary options, the Incremental and Completa re-ingestion of what is already in the graph. Shows "Atualizando…" while any of them runs. See updating data from the source URL.
Limpar dadosEmpties the content while keeping the context — the button comes in amber, since it is a destructive action. See clearing a context's data.
ExcluirRemoves the context itself — a red button, with a confirmation dialog. It also takes the context's prompts and its Knowledge Catalog entries, so catalogue search stops returning a context that no longer exists. Protected system contexts appear disabled, with a "Protegido" tooltip on hover.
  1. Active-context sections — "Schema do Grafo — {context}" (structure of the graph database), "Embeddings — {context}" (semantic search vectors and active model) and "Prompts e Regras — {context}". Embedding generation runs on the server: the overall bar and the per-context cards come back when you reopen the screen, in progress or already at the outcome — the detail lives in the platform cache, not in the screen that started it (see Embeddings — one vector field per model).

The create and edit form includes the "Fontes de dados deste contexto" block, which lets you combine more than one source in the same context — detailed in the multi-source context guide —, the "Identificação dos dados" block (section below), the "Função deste contexto" block and the "Contextos de regra aplicados na triagem" block, both covered in the next sections.

What creating a context provisions

A context only works once it exists in three places: the graph database (entities and relationships), the search index (text and vectors) and the Knowledge Catalog (so anyone can find it). Saving the form provisions all three — each with a different failure rule, and all of them visible:

What is provisionedWhenIf it fails
Graph database (Neo4j)before the registration is writtenthe context is not created, and the message tells "Neo4j is down" apart from "automatic provisioning is disabled because the Neo4j password is not configured"
Search index (OpenSearch)right after the databasethe context is created and the report shows the pending item, with what to do to create the index
Index pointer in the registrationtogether with the registrationcannot fail: when blank, the platform derives and stores the conventional name
Default context promptsafter the registrationthe context still works; prompts are rebuilt on first read
Knowledge Catalog entryin the backgroundthe context stays usable; the entry can be redone later

Why the database comes before the registration. It used to be created after the context was stored, and the failure only reached the technical record: the context was saved pointing at a database that might not exist, and the screen answered success. That is how a context measured in production was born with its database up, no index, an empty index pointer and no dataset in the catalogue — without a single warning in the interface. The database is now a precondition: if it does not come up, nothing is stored.

The index is the deliberate exception: a brand-new context has no text to lose, and the index can be recreated later with no side effect. So its failure does not abort the registration — but it becomes a warning on screen, never just a technical record.

Before saving: the screen states what it will create

In the "Fontes de dados deste contexto" block, when you pick no source the platform derives the destinations from the internal name — and now says so before you save, in amber:

"Nenhuma fonte selecionada: a plataforma vai criar o banco Neo4j maira-ctx e o índice de busca datta_mairactx para este contexto."

The notice informs, it does not block: deriving automatically is the intended behaviour — the defect was that it was silent. If the internal name is still blank, the notice says so instead of quoting an empty name.

After saving: the creation report

Saving opens a "Contexto criado — {label}" card showing:

  • the Neo4j database and the search index actually provisioned (the values the server returned, not the screen's guess);
  • the "Ficou pendente:" list, with whatever was created with a caveat — for example, the search index that did not come up, with the sentence telling you where to check OpenSearch and how to recreate it, or a court case context created without the procedural code database (its "Gerar recurso" will query the CPC — see multi-source context, section "Procedural code database"), or with a database that does not exist in Neo4j yet (the appeal comes out without articles and case law until the database is loaded);
  • the progress of the initial load of legislation, when you supplied a URL (section below).

With no pending items the card is neutral; with a pending item or a failed load it turns into an error card. The card exists because "created successfully" and "created halfway" were, until now, indistinguishable on screen.

Refusals on creation

All of them return a Portuguese message stating what to fix, and nothing is stored:

RefusalWhy
Name already used by another contextduplicate identity
Name that would produce the same index as another contextthe index drops hyphens, underscores and accents, so maira-ctx and mairactx would fight over datta_mairactx — both contexts would read from and write to the same place, with no error at all. The message names the conflicting context and the index.
Platform-reserved database (a name starting with datta-)those are the system databases; a context pointed at one of them would start reading and writing inside the platform's internal store
Name whose index would land on a platform system indexrum, prompts, conversations, glossary (and any name starting with glossary or capabilities, such as glossaryTermos) would produce datta_rum, datta_prompts, datta_glossary… — the platform's telemetry, prompt, history and glossary indices. The context would read and write inside the internal state, and deleting it would erase that state. The message names the conflicting system index.
Search index outside the conventionthe platform always reads and writes datta_{normalised name}; the message states the accepted value, or leave the field blank
Procedural code database that does not become a database name, or that points to a system databasethe name is normalised like the context's own database (lowercase, no accents, spaces or underscores — CLT becomes clt); whatever is not left as a valid name, and the system databases (datta-*, neo4j, system), are refused with a message naming the field. Also applies on edit — and when the edit also changes the internal name, the refusal comes before the rename: nothing is renamed
Description longer than 2,000 charactersthe description goes to the registry, to the system graph and to the chat's context ranking; the cap avoids storing unbounded text
Missing context type or data identificationsection below

Context type and data identification

The Tipo de contexto field is mandatory and states what kind of data the context holds. The categories come from a platform catalogue — declaring a new category is registration, not a code change — and today they are:

Context typeWhat it is forAnchor entity
Processo Judicialcase files, keyed by CNJ numberProcesso / processoNumero (suggested)
Código Processuallegal corpora (CPC, CPP, CDC, Constitution)does not anchor an entity
Dossiê Cadastral (KYC/KYB)company dossiers keyed by CNPJEmpresa / cnpj (suggested)
Análise de Créditocredit applications, individual or corporateyou declare it (e.g. Emprestimo / numeroPedido)
Customany other nature, with a typed subtypedoes not anchor an entity

When the chosen type keeps its data in an entity of its own, the form shows the "Identificação dos dados" block with two mandatory fields:

  • Entidade âncora — the name of the graph node that aggregates the context's data (initial capital, singular: Processo, Empresa, Emprestimo).
  • Propriedade identificadora — that node's unique property. It is what ties documents, analyses and the workflow to the right record (processoNumero, cnpj, numeroPedido).

Types that carry a suggestion fill both fields in as soon as they are selected; Análise de Crédito deliberately has none — a credit application is neither a CNJ number nor a CNPJ, and inheriting either would make the platform look for the key where it never was.

Saving without those fields is rejected, with a message stating what to fill in. The rejection exists because the silent failure is worse than the error: a context without identification does not break — it starts looking for everything as if it were court cases (:Processo by processoNumero), finds nothing and says nothing. That is how one dossier context ended up registered with a null identification.

Contexts already registered without identification keep working and stay editable: the requirement applies to a new context and to anyone changing the context's type. If you have one of those, open it, fill both fields in and save.

This context's role: when it is a rule corpus

In the creation form, the "Função deste contexto" block carries a single checkbox:

☐ Este contexto guarda legislação/normas e serve de corpus de regras para a triagem

Ticking it puts the new context into the list of visible rule corpora — the same list that feeds the Screening Rules editor and the "Contextos de regra aplicados na triagem" block of every other context. It is what CPC, CPP, CDC and FEBRABAN already are.

*There is no — and must be no — context type called "rule". What makes a context a rule corpus are two things, and neither is the category: (a) its name appearing in the rules written for that corpus and (b) its presence in the list of visible corpora. The measurement backs the decision: FEBRABAN is of type Custom and works as a rule corpus, with its own rules in production; CPC, CPP and CDC are of type Código Processual*. Creating a new category for the same concept would give two diverging mechanisms for one question — and the day they disagreed, nobody would know which one holds.

Two guarantees on write, because both failures would be silent:

  • the existing list is read and appended to, never replaced. Writing only the new name would wipe CPC, CPP, CDC and FEBRABAN in one go, with the screen saying "success";
  • an empty list does not mean "no corpus" — with no items there is no filter, and every context already counts as a corpus. Writing [new] over the empty list would hide all the others. In that case nothing is written.

If the write fails, the context is still created and the report carries the pending item, telling you where to add it by hand.

The checkbox appears only when creating. It is deliberately absent from the edit form: the field belongs to creation, and showing it on edit would collect a choice the save discards — exactly the kind of mute field this revision removed. To adjust it later, use the visible-contexts list under SistemaRegras.

Initial legislation load

The "URL de origem dos dados" field (formerly "URL da legislação") does two things. It is saved on the context — it comes back filled in when editing, and it is the address the Atualizar dados button uses (next section). And when you fill it in and tick the rule-corpus checkbox, the platform starts the initial load against the context that has just been born — never against the session's active context — and tracks it inside the creation card itself, with a progress bar and the current activity.

The URL must start with http:// or https://, with no spaces; otherwise the save is refused with a message stating the expected format. Leaving the field blank when editing clears the saved source.

Whatever prevents the load becomes a notice on the card, instead of silence:

SituationWhat the screen says
URL not starting with http:// or https://the load is not started and the card explains the expected format
You lack the document upload permissionthe context is created and the card warns that the load needs someone who holds it
URL filled in with the corpus checkbox untickedthe card says the URL was saved but the initial load was not started — use Atualizar dados
Failure during the loada Portuguese message with the reason, no raw error code

Closing the card only stops the tracking; the load carries on and can be followed in Execution History.

A legislation context in a single call

A law context (Lei 9.784, CLT, IN 2110, Decreto 70.235) is always born the same way: type Código Processual with the Legislação Federal option, marked as a rule corpus, with the official URL saved as the source, the context's own prompts and the initial load of the page. Until 2026-09-13 those steps were a recipe that lived only in scripts and in the operator's memory — and the Captain could only run it if you dictated every step.

The recipe is now one platform operation, available in the portal's API section (endpoint reference, Users, Permissions & Contexts group) and, through it, in the Captain: ask "create the LEI-9784 context from the Planalto URL with these prompts" and it makes the whole call. The request carries:

FieldWhat it is
nameinternal name (e.g. LEI-9784); the graph database and the search index derive from it by convention
displayNamelabel shown; blank uses the name itself
urlDaLeithe law's official page; saved as the source URL (the one Atualizar dados uses)
promptsoptional — the context's prompts, one per type: system, user, ner, audit, extraction, investigation, process_type, knowledge.doc, knowledge.faq, knowledge.glossary, knowledge.tone. Whatever is missing keeps the default prompt. captain is rejected: Captain's instructions belong to the installation (System > Captain), not to the context
ingerirfalse creates the context and saves the prompts without starting the load; absent means true

The order is fixed and matters: the Legislação Federal option is guaranteed in the type catalog; the context is created through the same path as the screen (database, index, registration, rule corpus, catalog); the prompts are saved before the load, because the load's entity extraction reads the context's NER prompt; finally the load is started and runs in the background — the response carries the task identifier and it shows up under Atualizar dados and in the executions panel as "Atualizar dados do contexto".

Whatever blocks a step does not vanish along the way:

SituationWhat the response says
Name already exists or is invalid, or a prompt key outside the listrefused with the reason, before creating anything
The graph database could not be createdrefused; the context is not created
A prompt was not saved (for instance, you lack the prompt-editing permission)the context exists; the notice names the prompt and the reason, and prompts.faltando lists what kept the default
The load could not be started (for instance, without the document upload permission)the context and the prompts exist; the notice states the reason and ingestao.iniciada comes back false — start it later under Atualizar dados

The criar-contexto-lei-9784.sh and criar-contexto-clt.sh scripts still exist, but they became wrappers around this single call: they define the law, read the prompt files and follow the load; the recipe lives in the platform.

criar-contextos-leis-trabalhistas.sh follows the same pattern for three stand-alone labor laws, one context per law, created in sequence:

ContextLawOfficial page
LEI-7998Lei 7.998/1990 — Unemployment Insurance and Salary Bonusl7998compilado.htm
LEI-8036Lei 8.036/1990 — Severance Indemnity Fund (FGTS)l8036compilada.htm
LEI-4090Lei 4.090/1962 — Christmas Bonus (13th salary)l4090.htm

It takes the same options as the others (--conferir, --sem-carga, --sem-acompanhar) and stops at the first law that fails. Before the first registration it checks that each law's 11 prompts exist and are not empty; if any is missing it creates nothing — a context created with the built-in prompts is not fixed by running again, only by rewriting each prompt in System → AI. When run again, it skips the contexts that already exist and only creates what does not exist yet; it does not redo a failed load. If the context was created and the load failed or did not finish (exit code 3), redo it under Atualizar dados. Each law's prompts come from the repository's prompts folder, one subfolder per context; PROMPTS_BASE changes the parent folder when the script runs outside the repository. As in the other law contexts, the provisions carry the LEI prefix and an article with a letter after the ordinal gets its own identifier (Art. 2º-C → LEI_ART_2_C).

To release and create the three laws with a single command, run from the operations machine, use release-com-contextos-leis-trabalhistas.sh. It checks the admin token before starting (expired or without the ADMIN role, it stops at once), runs the full release, waits for the configuration, prompts and documents services to come up, checks that the documents service already has the structurer that keeps lettered articles apart, copies the scripts and prompts to a temporary folder on the server, creates and loads the three laws and shows the result with --conferir. The token stays in a local file with permission 600, named in DATTA_JWT_FILE; it is not written on the server.

bash
DATTA_JWT_FILE=~/datta.jwt ./scripts/release-com-contextos-leis-trabalhistas.sh

Use --sem-release when the platform is already on the right version, --conferir to only see what exists and --sem-carga to create without loading the text. Anything after -- goes to the release script.

Updating data from the source URL

Legislation and case-law contexts (CPC, CPP, CDC, Lei 9.784, IN 2110…) are born from an official page and change when it changes. Instead of remembering the address and redoing the load in ProcessarUpload, use the Atualizar button in the action bar, under Configurações por Contexto:

  1. Select the context in the selector.
  2. Check, under Editar, the URL de origem dos dados field — that is what will be used. Without a saved URL, with more than one data source, or without the URL-load permission, the URL actions are disabled and the modal says why.
  3. Click Atualizar. The "Atualizar dados — {context}" modal opens, showing the source URL and offering two actions:
    • Atualizar agora — starts the same URL ingestion as the Upload screen's URL tab, against this context and with the "update the whole base" option on: changed provisions get the new wording, unchanged ones are kept.
    • Agendar — opens the platform's schedule editor (the same one as the URL tab and batch screening): once, every N hours, daily, weekly or monthly, with the next runs computed by the server. The Datta Scheduler fires it, with the same load as "Atualizar agora". Requires the DOCUMENT_SCHEDULE permission.
  4. The progress bar shows inside the modal itself, with the current activity, the source URL and a Cancelar button. When done it shows how many documents were loaded; on failure, a Portuguese message and Tentar novamente. Closing the modal does not stop the update: the action-bar button stays at "Atualizando dados…" and reopening it resumes the tracking.
  5. Under Re-ingerir a partir do grafo, the Incremental and Completa options redo the legislation and case law that are already in the graph of the context (by the address stored on each law), with a diff report and semantic drift — the former "Atualizar"/"Completa" pair of the action bar. They do not use the source URL: a still-empty context ends with "Nenhuma legislação encontrada", and the right path is Atualizar agora.
  6. Below, the modal lists the scheduled updates of this context, with the next run and the Editar, Pausar / Retomar and Remover buttons — what was already loaded is always preserved.

Contexts created before the source URL. Law contexts registered before 2026-09-03 were born without a saved URL. The script scripts/preencher-source-url-contextos.py fills the field from the PAF legal-basis manifest and the prompts' source_url.txt, and the seed-contextos-base-legal-paf.sh seed now writes it at registration.

Planalto only answers browsers. The Planalto portal does not deliver the page to a plain HTTP client (the response simply never comes). That is why the legislation load fetches the page with a real browser (Chromium via Playwright, the same used for the CPC load), falling back to plain HTTP only if the browser fails. The RFB norms portal is read through its API, with no browser.

The run is asynchronous: leaving the screen does not stop it. It shows up in the console's Execuções em segundo plano panel as "Atualizar dados do contexto — {context}", and clicking it brings you back to this screen, on the right context, with the bar re-attached to where the run actually is.

Only for contexts with a single data source. Contexts that combine several Neo4j databases — one per origin, like FEBRABAN (CVM, BCB, negative base) — have no single URL that stands for "the context's data". There the button is disabled, and hovering explains: the context has more than one data source. Each origin is refreshed by its own DATTA Extract load.

The URL actions require the DOCUMENT_UPLOAD permission (the same as the Upload URL tab); without it, they are disabled with the permission notice. Schedules created here are the same ones listed under Cargas de URL agendadas on the Upload URL tab — see scheduled URL load for the repetition details.

Rule contexts applied by screening

This block is the inverse of the previous one: there the context is the corpus; here it consumes corpora from others. They are independent axes — a collection context consumes CPC and CDC without being a corpus of anything; a legislation context is a corpus and usually consumes none.

Right below the data sources, the form brings the "Contextos de regra aplicados na triagem" block: a checkbox list with the available rule contexts (the same ones the Screening Rules editor shows, with the same label). It answers a question the data context alone cannot answer:

The data context saysThe rule contexts field says
where the cases are — the graph base, the search indiceswhich code judges those cases — CPC, CPP, CDC or several together

They are independent axes, which is why they are different fields. The same collection may be judged by more than one code (a civil context with consumer relations declares CPC and CDC), and the same code serves several collections. Tick one or many: screening evaluates the union of the rules of everything ticked, without repeating a rule that belongs to more than one code.

What the screen shows as you select:

SituationWhat appears
None tickedAmber warning: "Nenhum contexto de regra selecionado: a triagem deste contexto NÃO vai avaliar regra nenhuma, e o laudo vai registrar isso."
One ticked"A triagem vai avaliar as regras de: {label}."
Several ticked"A triagem vai avaliar a união das regras de N contextos: {labels}."
A stored value that no longer existsThe item stays in the list, flagged in amber with "• não existe mais — desmarque"

That last case matters: if a rule context is removed or renamed after being declared, it stays visible so you can untick it. Otherwise the value would be invisible on screen and saving would start failing with "nonexistent context" for no apparent reason.

Saving sends the complete list. Unticking everything and saving clears the configuration — and screening for that context starts refusing. That is not a side effect: it is the only explicit way back to the "not declared" state.

A nonexistent rule context is refused when saving, with a message in Portuguese listing the available ones. Order matters: the first ticked context is the primary one and governs the prompts, the case law consulted and the label shown in the report; the rules come from all of them.

The setting is read on every screening run — change it here, launch screening right after, and the new value is already in effect, with no restart and no wait.

What happens when a context declares nothing

Screening refuses and says what to do, instead of guessing: each case appears in the live view in red with the reason "O contexto '{nome}' não declara quais contextos de regra se aplicam a ele. Abra Sistema > Contextos > Gerenciar, edite o contexto e preencha 'Contextos de regra aplicados na triagem'; depois repita a triagem." No AI analysis is spent.

Why refusing. Until 2026-08-08 the platform inferred the applicable code from loose words in the case text. Measured in production: a civil enforcement case against the public treasury was sent to a code that does not exist on this platform — inheritance from an earlier project that survived in the code — because the word "administrativo" appeared in summaries quoted in the file. The report came out "completed" with zero rules evaluated, indistinguishable from a genuinely audited case. The three codes the platform actually has, measured on the same date: CPC with 1,076 rules, CPP with 748 and CDC with 106.

Replacing inference with configuration closes both ends: the wrong value is refused when saving, and the missing value is announced when screening.

If you edited contexts before 2026-08-08

Until that date there was a defect in saving: every context edit silently erased three settings that are not in the form — the context's reasoning model, the identifier label and the fixed rule context. The same loss happened when applying a reasoning model to all contexts at once.

Nobody noticed because reads returned the already resolved value, with the default derived from the context type: the zeroed field kept looking filled. If you edited contexts before that date, it is worth opening each one and checking the reasoning model and the identifier label — and, now, ticking the rule contexts.

Context Visibility Matrix

The matrix maps which features may use each context's data: one row per registered context and six checkbox columns — Painel de Regras, Upload PDF, Upload URL, DATTABI, DATTA Extract and Ontologia. The table is built from a feature catalog in the frontend itself, so a new column shows up without a layout change.

  • Empty list = all contexts visible: unticking everything in a column falls back to every context being visible — there is no way for the administrator to "lock themselves out".
  • Immediate persistence: every click saves right away and survives a page reload. The Painel de Regras column also notifies the rules screens that are already open, which reload the context list in real time.
  • Recognized features: the generic write accepts only dattabi, extract and ontology; an unknown feature is refused with an error message in Portuguese.
  • Parallel loading: all six columns are fetched at the same time when the page mounts, not one after the other.

Where each preference is stored:

ColumnWhere the preference is stored
Painel de RegrasPlatform global settings (legacy format)
Upload PDFPlatform global settings (legacy format)
Upload URLPlatform global settings (legacy format)
DATTABIPer-feature visibility file (context-visibility.json)
DATTA ExtractPer-feature visibility file (context-visibility.json)
OntologiaPer-feature visibility file (context-visibility.json)

Reading and writing each column is also available to integrations — see the API reference.

How far the visibility is enforced today

FeatureHow the visibility is enforced
Painel de RegrasFilter applied on the server: the rules screens (Batch Screening included) already receive only the visible contexts.
Upload PDF / Upload URLThe upload screen reads both lists and filters the contexts. On a network failure it degrades by showing all of them (fail-open).
OntologiaThe investigation screen filters the contexts through the matrix, also fail-open.
DATTABI / DATTA ExtractThe preferences are stored and exposed, but there is no enforcement yet on those screens: today they operate on connections and datasets, without enumerating contexts. Follow-up recorded in the backlog.

The matrix is interface and governance visibility, not a server-side per-context data access control list. To restrict who accesses what, use roles and permissions.

Hands-on example — creating a context from scratch

Your team is about to screen consumer-law cases and needs its own context, separate from the civil one:

  1. In SistemaContextos, click + Novo Contexto.
  2. In the "Adicionar Novo Contexto Legal" form, fill in both names (see Internal name vs. label just below) and the description: the Nome interno (e.g. Consumidor) and the Rótulo de exibição (e.g. "Código de Defesa do Consumidor").
  3. In the "Fontes de dados deste contexto" block, tick the sources it uses.
  4. In the "Contextos de regra aplicados na triagem" block, tick CDC — and CPC as well, if the collection also holds ordinary civil cases. The screen confirms below: "A triagem vai avaliar a união das regras de 2 contextos: CPC, CDC." Under "Função deste contexto", leave the checkbox unticked: this context holds cases, it is not itself a corpus of norms.
  5. If you picked no sources, check the amber notice with the database and the index that will be created. Save.
  6. Read the "Contexto criado" card: it shows the database and the index provisioned and, if any, the "Ficou pendente:" list. With no pending items the context already appears in the selector — ready for ingestion.
  7. In the Visibility Matrix, tick where it should appear (e.g. only Painel de Regras and Upload PDF while it is in pilot).

Context description

The form's "Descrição do contexto" field is optional and is stored in the context: editing reopens with the saved text, and integrations read it from the description field of the context lookup. Until 2026-09-27 the text was silently discarded — the screen sent it, the server did not keep it, and editing came back with the field empty.

The description also goes to the platform's system graph — the descricao property of the context node in the datta database (and in the audit database replica):

SituationDescription in the system graph
You typed a descriptionyours, on every save
Blank fieldthe automatic one, "Contexto {label} — cadastrado pela interface", which follows the label: change the label and the description changes with it
Context seeded by the installation with its own description (e.g. cpc)the installation's is kept until you type another
You erased the description you had typedback to the automatic one

On edit, leaving the field as it came keeps the description; erasing the text and saving clears it. The automatic description is also recomputed whenever the configuration service starts, so a context whose label changed before this fix starts showing the right label without being edited.

The typed description also weighs in the chat. In a question that queries several contexts, the chat compares the question with a text describing each context (label, type, description and sources) and gives up to 40% more score to the results of the closest context. A description that talks about "companies and partners" pulls the context up in CNPJ questions, even if it holds court cases — describe what the context contains. That text is kept for up to 24 hours: changing the description (like the label, type or sources) takes up to that long to change the order of the answers.

Internal name vs. label

Every context carries two names, and the distinction matters the day you drive the platform through its API.

Internal nameDisplay label
exampleProcessosProcesso Tributario
asked forat creation (derived from the label)at creation, and editable afterwards
mutable?yes — but it is a migration, not an edityes, whenever you want
where it showsmonospace field on the edit formeverywhere in the platform
what it is forthe value of ?domain= in API callswhat people read

Where to find it: open Editar on the context. The "Nome interno" block, in monospace with a copy button, is the key the API expects.

Renaming the internal name

The internal name is editable in the same Editar form. It is not a label: it is stored in the domain field of every indexed passage, in the names of the context's search indices and in every external integration that already references it. Saving a new name therefore triggers a migration — the screen asks for confirmation and describes what will happen before writing anything.

What the platform moves on its own, within the save itself:

  • The context's OpenSearch indices — text, vectors and chat history — move to the new name in an atomic swap, both together. For a few seconds they are blocked for writes; the platform makes an identical copy of each one (the same fields, the same vectors, the same compression), checks that the copy has the same documents — in total and in every vector field — and swaps the names at once. Whatever arrives in those seconds (a chat answer kept as memory, an indexed passage) waits for the swap to finish and lands in the new index: nothing is lost.
  • The old name keeps working as an alias of the new index. The chat, which still uses the old name for a few minutes, a tab opened before the rename and a load in progress keep reading and writing in the right place.
  • Each document's domain field moves to the new name right after, in the background. On an OpenSearch version that cannot safely rewrite documents with a compressed vector, the report says so and the field keeps the old name — search does not depend on it, only the origin shown in a result does. The same applies to what is written later through the old name.
  • The context's prompts (index datta_prompts).
  • The :Contexto node in the system databases datta and datta-audit-db.
  • The active context, the three global Visibility Matrix lists (Painel de Regras, Upload PDF, Upload URL) and those of the remaining features.
  • The workspaces that include the context.
  • The rule contexts of other contexts that point at this one.
  • The Knowledge Catalog datasets, which start listing the new name. Without that repoint the same dataset would appear twice in catalogue search — once per name — because the fresh scan publishes the new entry without removing the old.
  • The context's BPM process models and instances. Without this, every model of the context would become an orphan at once (the very state the context validation on model creation exists to prevent) and instances would stop resolving owner, title and enrichment.

What does not change: the context's Neo4j database. It is a stored value, not derived from the name, so the graph stays exactly where it was — the "Careful" note below still applies after a rename.

What is left to you:

  • Every external integration calling the API with ?domain=<old name> must switch to the new name. The platform has no way of discovering those callers; the report shown at the end of the rename says so.

Known refusals — in all of them nothing is changed and the context stays intact under its current name:

  • A name already used by another context.
  • A name that would collide on the index of another context. Index names drop hyphens, underscores and accents (datta_{letters and digits only}), so base-negativa and base_negativa would fight over the same datta_basenegativa and both contexts would start writing to the same place. Pick a name that differs by letters or digits.
  • A name whose index would land on a platform system index (rum, prompts, glossaryTermos…) — the same refusal as on creation, with the message naming the conflicting system index.
  • There is already content in the new name's index (for example, the chat history of an old context that had that name). Renaming on top of it would mix the two.
  • Another rename of the same context, its deletion or the chat history maintenance in progress. Wait for it to finish and save again.
  • A failure while moving the indices (OpenSearch down, for instance). The platform undoes the rename before answering — it deletes the partial copies and gives write access back to the indices — and no configuration is written: the data stays intact under the old name and the operation can be retried. If the rollback does not finish, the message says exactly what was left behind.

When the context index lives on an external data server, it is moved right there, and the chat history stays on the platform server. The two swaps happen in sequence; if the second one fails, the message says what has already changed name and what has not — nothing is lost, the internal name is not changed, and saving again completes what was missing.

If the answer does not arrive in time, the message says the state of the indices is uncertain: the internal name was not changed, the current name still leads to the content, and the rename can be repeated — it recognises what was already moved and only completes what is missing.

The swap takes seconds even on large contexts: the copy does not rewrite document by document.

Renaming back to a name the context already had works: the old alias is reused. And creating a new context with another context's old name works too: the new context takes the name back, and the alias stops leading to the renamed context's content.

Careful. The internal name is not the database name. In the Processos context, for instance, the database is called processotributario and the label is "Processo Tributario" — three distinct strings, and only the first works in ?domain=. Passing the database name makes the endpoint answer that the context was not found.

Learned substitutions

Each context keeps what the chat learned from the people who use it:

  • Confirmed missing entity — the question named an entity the data model does not have ("accountant") and the person confirmed using the closest one ("Pessoa"). The pair is suggested in the next questions, but confirmation stays mandatory every time: swapping the entity changes the question. A refusal also counts, as a contrary signal.
  • Property synonym — a term of the question that matches a property of the data model under another name ("company name" → Empresa.empresaNome). It applies by default, no question: it is interpretation, not a swap.

The Learned substitutions section in the context detail lists the pairs with their type, how many times they were confirmed, refused or used, and the last decision. Every pair is validated against the context's current graph schema: if the label or the property no longer exists, the pair shows as obsolete and is no longer suggested to the chat. With configuration edit permission you can add a pair by hand (the target must exist in the schema; for a property, in the form Label.property) and forget any pair. Adding and forgetting go to the audit trail, and the chat reflects the change within 15 minutes (the pairs' cache period).

Pairs belong to the context: a new context, with another data model, starts with none and learns from use. They are not shared between contexts and disappear when the context is deleted.

Who can use it

  • Viewing the screen, the matrix and the lists: CONFIG_VIEW.
  • Changing the matrix and the per-context settings: CONFIG_EDIT.
  • Clearing data: CONTEXT_PURGE (sensitive permission) — see clearing a context's data.
  • Starting the initial legislation load along with creation: DOCUMENT_UPLOAD. Without it the context is created as usual and the card warns that the load was not started.
  • Creating a legislation context in a single call: CONFIG_EDIT for the registration, and the call uses your identity for the following steps — PROMPT_EDIT for the prompts and DOCUMENT_UPLOAD for the load. Whatever your permission does not cover comes back as a notice, never silently.

How to grant each one is covered in the roles and permissions guide.

UX history

  • 2026-06-11 — the "+ Novo Contexto" button moved up into the page header (it used to sit in the middle, next to the selector); the edit button started showing only "Editar" (it used to repeat the name of the active context, e.g. "Editar PROCESSOS"); the Visibility Matrix was removed under the assumption that workspaces would cover visibility.
  • 2026-06 — the Visibility Matrix came back at the user's request, now built from the feature catalog and expanded with DATTABI, DATTA Extract and Ontologia. The header with "+ Novo Contexto" and the "Editar" label from the earlier change remain.
  • 2026-09-27 — the edit form opens empty with Save disabled ("Carregando...") until the context's data arrives; if it does not arrive, the red message states why and Save stays disabled — close and reopen the edit. Cancelar and the X clear the form, and the response for a context you already closed is discarded. Before, opening another context right after closing one showed the previous one's fields, and saving there wrote one context's data over another. On the same date the description started being stored, and editing started showing the save's warnings (e.g. a court case without the procedural code database, or a database that does not exist in Neo4j) in a notification. An edit that changes the internal name and carries an invalid procedural code database started being refused before the rename — before, the context was renamed, the other changes were lost and the next Save answered "Contexto não encontrado".
  • Multi-source context — heterogeneous data sources per context.
  • Clearing a context's data — emptying the content while keeping the context.
  • Context Visibility Matrix — visibility governance per feature, in detail.
  • Batch Screening — where the rule contexts configured here are applied.
  • Graph database naming — system databases versus context databases.
  • Context provisioning — the order, the contracts and the known limitations of what creation provisions (restricted reading).