Appendix

This is the public preview documentation of Neo4j Virtual Graph. To provide feedback, please use the feedback form you were granted access to.

During the public preview, we advise you not to use sensitive or production data with Virtual Graph.

Metrics

Virtual Graph does hook into the standard Neo4j metrics system and collects various metrics per data source when enabled. The required settings in neo4j.conf are:

internal.metrics.enable=true
# Adapt accordingly for all other metrics you want to see
server.metrics.filter=*virtual_graph*

The available metrics, grouped by datasource type, are:

  • neo4j.dbms.virtual_graph.internal.connections_created: Connections created. (counter, histogram)

  • neo4j.dbms.virtual_graph.internal.connections_acquired: Connections acquired. (counter, histogram)

  • neo4j.dbms.virtual_graph.internal.connections_used: Connection usage. (counter, histogram)

  • neo4j.dbms.virtual_graph.internal.connections_timed_out: Connections timed out. (counter)

  • neo4j.dbms.virtual_graph.internal.queries: Total number of queries per datasource. (counter)

  • neo4j.dbms.virtual_graph.internal.queries_failed: Number of queries per datasource that failed. (counter)

  • neo4j.dbms.virtual_graph.internal.query_time_elapsed: Time elapsed for successful queries per datasource. (counter, histogram)

  • neo4j.dbms.virtual_graph.internal.rows_processed: Number of rows processed. (counter)

  • neo4j.dbms.virtual_graph.internal.columns_processed: Number of columns processed. (counter)

JSON schema for schema.json

The deserializer does support sourceColumn/targetColumn pairs on the entity references in addition to the array types described below. They are useful for all cases in which the relational schema does not use composite keys and makes your schema a bit more readable.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://neo4j.com/schemas/graph-engine-schema.json",
  "title": "Neo4j Virtual Graph Schema",
  "type": "object",
  "required": ["catalog", "schema", "entities"],
  "properties": {
    "catalog": {
      "type": "string",
      "minLength": 1,
      "description": "Catalog name in the relational database."
    },
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Schema name in the relational database."
    },
    "entities": {
      "type": "object",
      "properties": {
        "nodes": {
          "type": "array",
          "items": { "$ref": "#/$defs/node" }
        },
        "relationships": {
          "type": "array",
          "items": { "$ref": "#/$defs/relationship" }
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "$defs": {
    "property": {
      "type": "object",
      "required": ["name", "column", "type"],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the property as it will appear in the graph."
        },
        "column": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the column in the backing table."
        },
        "type": {
          "type": "string",
          "minLength": 1,
          "description": "Suggested graph type."
        }
      },
      "additionalProperties": false
    },
    "keyColumn": {
      "type": "object",
      "required": ["column"],
      "properties": {
        "column": {
          "type": "string",
          "minLength": 1,
          "description": "Name of the backing column that contributes to the entity identifier."
        }
      },
      "additionalProperties": false
    },
    "key": {
      "type": "object",
      "required": ["nodeColumn", "relationshipColumn"],
      "properties": {
        "nodeColumn": {
          "type": "string",
          "minLength": 1,
          "description": "Column inside the table backing the target node; MUST be part of that node's key."
        },
        "relationshipColumn": {
          "type": "string",
          "minLength": 1,
          "description": "Column inside the table backing this relationship; MUST be part of the relationship's key."
        }
      },
      "additionalProperties": false
    },
    "endpoint": {
      "type": "object",
      "required": ["targetEntity", "foreignKey"],
      "properties": {
        "targetEntity": {
          "type": "string",
          "minLength": 1,
          "description": "Label of the node entity referenced by this endpoint."
        },
        "keys": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/foreignKey" }
        }
      },
      "additionalProperties": false
    },
    "node": {
      "type": "object",
      "required": ["label", "table", "key"],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "The Neo4j node label."
        },
        "table": {
          "type": "string",
          "minLength": 1,
          "description": "The backing relational table."
        },
        "properties": {
          "type": "array",
          "items": { "$ref": "#/$defs/property" }
        },
        "key": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/keyColumn" },
          "description": "Columns that constitute the identifier for the entity. Must be unique in the backing table."
        }
      },
      "additionalProperties": false
    },
    "relationship": {
      "type": "object",
      "required": ["label", "table", "key", "start", "end"],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1,
          "description": "The Neo4j relationship type."
        },
        "table": {
          "type": "string",
          "minLength": 1,
          "description": "The backing relational table."
        },
        "properties": {
          "type": "array",
          "items": { "$ref": "#/$defs/property" }
        },
        "key": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/keyColumn" },
          "description": "Columns that constitute the identifier for the relationship. Must be unique in the backing table."
        },
        "start": { "$ref": "#/$defs/endpoint" },
        "end": { "$ref": "#/$defs/endpoint" }
      },
      "additionalProperties": false
    }
  }
}