Graph Modeling

Once your data sources are connected, the next step is to model your data as a graph: defining how tables become nodes and edges, and where each graph element draws its rows from.

PuppyGraph follows the labeled property graph model. A graph consists of:

• Nodes (also called vertices), the typed entities such as Person or Software.
• Edges, the typed, directional relationships between nodes, such as Person -[:KNOWS]-> Person.
• Properties, the key-value attributes attached to nodes and edges.

A PuppyGraph schema is a single JSON document that maps your tables onto this model. You can author it through the Schema Builder UI or upload a schema.json file directly. Once active, the schema can be edited in place from the UI without re-uploading.

Anatomy of a schema

A schema has up to five top-level sections:

Section	Purpose
catalog[]	Connections to external data sources. Per-source configuration is documented in Connecting.
node[]	Node types. See Building a Graph.
edge[]	Edge types. See Building a Graph.
localTable[]	Locally cached tables. Optional.
rowLevelSecurity	Per-user query filters. Optional.

A minimal schema with one catalog, one node type, and one edge type:

{
  "catalog": [
    {
      "name": "postgres_data",
      "type": "postgresql",
      "jdbc": {
        "username": "user",
        "password": "pass",
        "jdbcUri": "jdbc:postgresql://host:5432/postgres"
      }
    }
  ],
  "node": [
    {
      "label": "Person",
      "dataSourceGroup": {
        "externalDataSource": {
          "enabled": true,
          "catalog": "postgres_data",
          "schema": "modern",
          "table": "person"
        }
      },
      "id": [{ "name": "id", "type": "STRING" }],
      "attribute": [
        { "name": "name", "type": "STRING" },
        { "name": "age",  "type": "INT" }
      ]
    }
  ],
  "edge": [
    {
      "label":         "KNOWS",
      "fromNodeLabel": "Person",
      "toNodeLabel":   "Person",
      "dataSourceGroup": {
        "externalDataSource": {
          "enabled": true,
          "catalog": "postgres_data",
          "schema": "modern",
          "table": "knows"
        }
      },
      "id":        [{ "name": "id",      "type": "STRING" }],
      "fromKey":   [{ "name": "from_id", "type": "STRING" }],
      "toKey":     [{ "name": "to_id",   "type": "STRING" }],
      "attribute": [{ "name": "weight",  "type": "DOUBLE" }]
    }
  ]
}

What's in this section

• Building a Graph, mapping tables to nodes and edges, identifiers and keys, the Schema Builder UI, and advanced configurations (SCD2, row-level security).
• Data Sources and Local Tables, where the rows behind a node or edge come from: external catalogs, locally cached tables, or unions.
• Managing the Graph, inspecting and modifying the active schema in the Web UI, importing or exporting it as JSON, and the Local Table Management surface.
• Migrating from v0, for users coming from PuppyGraph 0.x.