visualizador_instanciados/backend_go/README.md

Backend (Go) – Graph + Selection API

This service exposes a small HTTP API for:

• Building and caching a “graph snapshot” from AnzoGraph via SPARQL (/api/graph)
• Returning available “graph query” and “selection query” modes
• Running selection queries for the currently selected node IDs
• (Optionally) issuing raw SPARQL passthrough for debugging

Run

Via Docker Compose (recommended):

docker compose up --build backend

The backend listens on :8000 (configurable via LISTEN_ADDR).

Configuration (env)

See backend_go/config.go for the full set.

Important variables:

• Snapshot limits:
  • DEFAULT_NODE_LIMIT, DEFAULT_EDGE_LIMIT
  • MAX_NODE_LIMIT, MAX_EDGE_LIMIT
• SPARQL connectivity:
  • SPARQL_HOST (default http://anzograph:8080) or SPARQL_ENDPOINT
  • SPARQL_USER, SPARQL_PASS
• Startup behavior:
  • SPARQL_LOAD_ON_START, SPARQL_CLEAR_ON_START
  • SPARQL_DATA_FILE (typically file:///opt/shared-files/<file>.ttl)
• Other:
  • INCLUDE_BNODES (include blank nodes in snapshots)
  • CORS_ORIGINS

Endpoints

• GET /api/health
• GET /api/stats
• GET /api/graph?node_limit=&edge_limit=&graph_query_id=
• GET /api/graph_queries
• GET /api/selection_queries
• POST /api/selection_query
  • Body: {"query_id":"neighbors","selected_ids":[1,2,3],"node_limit":...,"edge_limit":...,"graph_query_id":"default"}
• POST /api/sparql (raw passthrough)
• POST /api/neighbors (legacy alias of query_id="neighbors")

Graph snapshots

Snapshots are built by:

1. Running a SPARQL edge query (controlled by graph_query_id)
2. Converting SPARQL bindings into dense integer node IDs + edge list
3. Computing a layout and fetching optional rdfs:label

Snapshots are cached in-memory keyed by:

• node_limit, edge_limit, INCLUDE_BNODES, graph_query_id

Query registries

Graph query modes (graph_query_id)

Stored under backend_go/graph_queries/ and listed by GET /api/graph_queries.

Built-in modes:

• default – rdf:type (to owl:Class) + rdfs:subClassOf
• hierarchy – rdfs:subClassOf only
• types – rdf:type (to owl:Class) only

To add a new mode:

1. Add a new file under backend_go/graph_queries/ that returns a SPARQL query selecting ?s ?p ?o.
2. Register it in backend_go/graph_queries/registry.go.

Selection query modes (query_id)

Stored under backend_go/selection_queries/ and listed by GET /api/selection_queries.

Built-in modes:

• neighbors – type + subclass neighbors (both directions)
• superclasses – ?sel rdfs:subClassOf ?nbr
• subclasses – ?nbr rdfs:subClassOf ?sel

To add a new mode:

1. Add a new file under backend_go/selection_queries/ that returns neighbor node IDs.
2. Register it in backend_go/selection_queries/registry.go.

Performance notes

• Memory usage is dominated by the cached snapshot ([]Node, []Edge) and the temporary SPARQL JSON unmarshalling step.
• Tune DEFAULT_NODE_LIMIT/DEFAULT_EDGE_LIMIT first if memory is too high.