Brazil Unified Knowledge Architecture

This document is the single source of truth for the BrazilBR.online project – a definitive structured database and knowledge graph of Brazil. It contains the complete data architecture: entity taxonomy, SQL schema, seed data, API definitions, search engine mapping, and formal ontology.

All assets are production‑ready and can be used directly. Download links are provided for each component. The system is built on the principle that every entity has a persistent ID, typed relationships, source attribution, and machine‑readable representation.

Complete Entity Taxonomy

Entities are organized into domains. Below are the primary types (classes) defined in the ontology (see full OWL ontology).

Database Schema (PostgreSQL + PostGIS)

The core registry uses a relational model with geographic extensions. Every entity type maps to a dedicated table, all inheriting common metadata fields (ID, name, source, confidence, geometry, etc.).

⬇ Download full schema.sql (includes all DDL: tables, indexes, UUID functions, versioning, and relationship tables).

-- Core administrative hierarchy tables:
CREATE TABLE country (...);
CREATE TABLE region (...);
CREATE TABLE state (...);
CREATE TABLE mesoregion (...);
CREATE TABLE microregion (...);
CREATE TABLE municipality (
    id UUID PRIMARY KEY DEFAULT uuid_v7(),
    ibge_code CHAR(7) UNIQUE NOT NULL,
    name_pt TEXT NOT NULL,
    state_id UUID REFERENCES state(id),
    mesoregion_id UUID REFERENCES mesoregion(id),
    microregion_id UUID REFERENCES microregion(id),
    is_capital BOOLEAN DEFAULT FALSE,
    population INTEGER,
    area_km2 NUMERIC(12,4),
    geojson JSONB,
    centroid GEOMETRY(Point, 4326)
);
-- Additional tables: district, neighborhood, census_tract, postal_code, street, point_of_interest
-- Versioning: entity_version (table, id, version, snapshot JSONB)
-- Relationships: entity_relationship (subject/object table+id, predicate, properties JSONB)
            

All geometry is stored using PostGIS. UUIDv7 generation ensures time‑ordered, globally unique identifiers. The table entity_alias supports multilingual search.

Complete Seed Data

The database is pre‑loaded with the full administrative hierarchy of Brazil:

The complete municipality seed (all 5,568 rows with IBGE codes, names, and hierarchical UUIDs) is available as a separate, ready‑to‑run SQL file:
⬇ Download municipalities_seed.sql

IDs for administrative divisions are deterministically derived from the IBGE code using the formula: '00000000-0000-0000-0000-' || LPAD(code, 12, '0'), guaranteeing stable references without joins.

API Reference

REST API (OpenAPI 3.0)

Base URL: https://api.brasilbr.online/v1
Full specification: ⬇ openapi.yaml

GET /entities/{type}?q=search&limit=100&cursor=...
GET /entities/{type}/{id}
GET /entities/{type}/{id}/relationships/{predicate}
GET /search?q=...&geo=...&facets=true
POST /graph/query   (accepts Cypher queries)
            

Pagination is cursor‑based. Responses follow a JSON‑LD structure with @context.

GraphQL API

# Example query
{
  municipality(ibge_code: "3550308") {
    name
    population
    state { abbreviation region { name } }
    rivers { name length }
  }
}
            

Full schema: ⬇ schema.graphql

Search Engine Architecture

Powered by Elasticsearch with a custom Portuguese analyzer, supporting full‑text, faceted, geospatial, and vector (semantic) search.

• Autocomplete via search_as_you_type on names.
• Geospatial filtering: geo_distance, geo_bounding_box, geo_shape.
• Facets by entity type, state, biome, etc.
• Vector similarity for natural‑language queries (dense_vector field with 1024 dimensions).

⬇ Download Elasticsearch index mapping

Knowledge Graph Ontology (BUKGO)

The formal ontology (BUKGO) defines all classes, properties, and relationships. It is OWL‑compatible and serializable as JSON‑LD.

Key Classes

bukgo:Location > bukgo:Municipality, bukgo:State, bukgo:Region ...
bukgo:NaturalFeature > bukgo:River, bukgo:Biome, bukgo:Mountain ...
bukgo:Person > bukgo:Politician, bukgo:Artist, bukgo:Scientist ...
bukgo:Organization > bukgo:Company, bukgo:GovernmentAgency ...
            

All entities are linked to Wikidata (owl:sameAs) and other external IDs.

Relationships Catalog (Knowledge Graph Edges)

These are the typed predicates used in the entity_relationship table and the Neo4j graph.

The full list is part of the ontology definition. Relationships can carry temporal qualifiers and confidence scores.

Quick Deployment Guide

1. Install PostgreSQL 15+ with PostGIS extension.
2. Run schema.sql to create the database structure.
3. Run the included seed data (regions, states, meso/microregions, municipalities).
4. Set up Elasticsearch (8.x) with the provided index mapping.
5. Launch the API server (REST + GraphQL) – reference implementations available.
6. Connect Neo4j for graph traversal (optional for advanced queries).

For full integration instructions and enterprise support, see the developer portal.