# Esquema da base de dados FHIR

> Como armazenar recursos FHIR: tabelas normalizadas vs JSON com índices de pesquisa vs gráfico, o esquema PostgreSQL que o Anpheros executa (recursos, histórico, índices tipados, projeções) e as regras que importam.

Source: https://developers.anpheros.com/pt/guides/fhir-database-schema

**Uma base de dados FHIR armazena recursos HL7 FHIR para que possam ser lidos, pesquisados e versionados através da API FHIR; o esquema mais comum mantém cada recurso como JSON e preenche tabelas de índice separadas para os parâmetros de pesquisa, em vez de espalhar cada elemento por tabelas relacionais normalizadas.** Esta página explica os três designs usuais, o esquema que o Anpheros executa em PostgreSQL e quando não deve construir um você mesmo.

## Três formas de armazenar FHIR

<!-- visual:schema-compare -->

Os recursos FHIR são profundos, opcionais e extensíveis: uma Observação sozinha tem dezenas de elementos, tipos de escolha (`value[x]`), codificações repetidas e extensões. Normalizar isso em colunas relacionais significa uma migração sempre que um perfil adiciona um campo. Manter o recurso como JSON armazena qualquer coisa válida inalterada; as tabelas de índice tornam-no pesquisável.

## O esquema Anpheros

<!-- visual:schema-stack -->

| Tabela | Uma linha por | Colunas chave |
|---|---|---|
| `fhir_resources` | versão atual de um recurso | `resource_type`, `id`, `patient_id`, `version`, `json` (o recurso completo), `last_updated`, `deleted`, mais colunas de proveniência |
| `fhir_history` | todas as versões já escritas | `resource_type`, `id`, `version`, `json`, `last_updated` |
| `idx_token` | valor de pesquisa codificado ou de identificador | system, code — para `code`, `category`, `identifier`, `status` |
| `idx_string` | valor de pesquisa de texto | texto normalizado — para nomes e texto livre |
| `idx_date` | valor de pesquisa de data | início e fim do intervalo — para `date`, `onset-date`, `birthdate` |
| `idx_reference` | valor de pesquisa de referência | tipo de destino e id — para `patient`, `subject`, `encounter` |
| `idx_quantity` | valor de pesquisa de quantidade | value, system, unit — para `value-quantity` |
| `proj_observations`, `proj_conditions`, `proj_medications` | recurso, achatado | as colunas em que a API REST simples filtra |

Em cada escrita, a plataforma valida o recurso, escreve a nova versão para `fhir_resources` e `fhir_history`, substitui as suas linhas de índice e projeções, e regista a Proveniência. Uma pesquisa como `Observation?patient=…&code=http://loinc.org|4548-4&date=ge2026-01-01` torna-se joins em `idx_reference`, `idx_token` e `idx_date`; o resultado retorna o JSON armazenado tal como foi escrito.

## Regras de design importantes

- **Indexar apenas parâmetros de pesquisa declarados**, e recusar os desconhecidos com `400` em vez de os ignorar silenciosamente.
- **Nunca atualizar no local sem histórico**: as correções devem manter o que era conhecido anteriormente.
- **Eliminação lógica (soft delete)**: um recurso eliminado desaparece das leituras e pesquisas, mas as suas versões permanecem para auditoria.
- **Coluna de compartimento do paciente**: armazenar `patient_id` em cada recurso torna `$everything`, filtros de consentimento e isolamento por paciente baratos.
- **Validar antes de armazenar**: JSON inválido no armazenamento quebra todos os leitores posteriormente.

## Perguntas frequentes

### Qual é a melhor base de dados para FHIR?
A maioria dos servidores FHIR em produção utiliza uma base de dados relacional, como PostgreSQL, com o recurso armazenado como JSON (JSONB) e os parâmetros de pesquisa indexados em tabelas separadas. Combina armazenamento flexível com pesquisa rápida e padrão.

### Devo normalizar recursos FHIR em tabelas relacionais?
Normalmente não para o armazenamento primário. Tabelas normalizadas são adequadas para relatórios; mantenha-as como projeções construídas a partir dos recursos armazenados, como a Anpheros faz para a sua API REST mais simples.

### Como é que o HAPI FHIR armazena recursos?
O servidor JPA do HAPI FHIR também armazena cada versão do recurso como JSON serializado e mantém os parâmetros de pesquisa em tabelas de índice separadas. O design da Anpheros segue o mesmo princípio.

### Preciso de construir uma base de dados FHIR eu próprio?
Apenas se precisar de controlo total sobre perfis e tipos de recursos. Caso contrário, uma plataforma FHIR gerida oferece armazenamento, pesquisa, histórico, consentimento e auditoria sem ter de gerir o esquema.

<!-- visual:cta-schema -->

## Relacionados

- [FHIR vs. uma base de dados médica personalizada](https://developers.anpheros.com/pt/guides/fhir-vs-custom-database)
- [Como armazenar registos médicos usando FHIR R4](https://developers.anpheros.com/pt/guides/store-medical-records-fhir)
- [Base de dados e sandbox FHIR gratuitos](https://developers.anpheros.com/pt/guides/free-fhir-database)
- [Como o Anpheros se compara com outros servidores FHIR](https://developers.anpheros.com/pt/guides/fhir-server-comparison)
- [Plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir)