Listing graphs

Information about graphs in the catalog can be retrieved using the gds.graph.list() procedure.

1. Syntax

List information about graphs in the catalog:
CALL gds.graph.list(
  graphName: String
) YIELD
  graphName: String,
  database: String,
  configuration: Map,
  nodeCount: Integer,
  relationshipCount: Integer,
  schema: Map,
  schemaWithOrientation: Map,
  degreeDistribution: Map,
  density: Float,
  creationTime: Datetime,
  modificationTime: Datetime,
  sizeInBytes: Integer,
  memoryUsage: String
Table 1. Parameters
Name Type Optional Description

graphName

String

yes

The name under which the graph is stored in the catalog. If no graph name is given, information about all graphs will be listed. If a graph name is given but not found in the catalog, an empty list will be returned.
Table 2. Results
Name Type Description

graphName

String

Name of the graph.

database

String

Name of the database in which the graph has been projected.

configuration

Map

The configuration used to project the graph in memory.

nodeCount

Integer

Number of nodes in the graph.

relationshipCount

Integer

Number of relationships in the graph.

schema [1]

Map

Node labels, relationship types and properties contained in the projected graph.

schemaWithOrientation

Map

Node labels, relationship types, relationship orientation and properties contained in the projected graph.

degreeDistribution

Map

Histogram of degrees in the graph.

density

Float

Density of the graph.

creationTime

Datetime

Time when the graph was projected.

modificationTime

Datetime

Time when the graph was last modified.

sizeInBytes

Integer

Number of bytes used in the Java heap to store the graph. This feature is not supported on all JDKs and might return -1 instead.

memoryUsage

String

Human readable description of sizeInBytes. This feature is not supported on all JDKs and might return null instead.

1. In the next major release this field will get the semantics of schemaWithOrientation.

The information contains basic statistics about the graph, e.g., the node and relationship count. The result field creationTime indicates when the graph was projected in memory. The result field modificationTime indicates when the graph was updated by an algorithm running in mutate mode.

The database column refers to the name of the database the corresponding graph has been projected on. Referring to a named graph in a procedure is only allowed on the database it has been projected on.

The schema consists of information about the nodes and relationships stored in the graph. For each node label, the schema maps the label to its property keys and their corresponding property types. Similarly, the schema maps the relationship types to their property keys and property types. The property type is either Integer, Float, List of Integer or List of Float.

The schemaWithOrientation is an extended version of the schema, where for each relationship types it maps to their orientation and properties.

The degreeDistribution field can be fairly time-consuming to compute for larger graphs. Its computation is cached per graph, so subsequent listing for the same graph will be fast. To avoid computing the degree distribution, specify a YIELD clause that omits it. Note that not specifying a YIELD clause is the same as requesting all possible return fields to be returned.

The density is the result of relationshipCount divided by the maximal number of relationships for a simple graph with the given nodeCount.

2. Examples

In order to demonstrate the GDS Graph List capabilities we are going to create a small social network graph in Neo4j.

The following Cypher statement will create the example graph in the Neo4j database:
CREATE
  (florentin:Person { name: 'Florentin', age: 16 }),
  (adam:Person { name: 'Adam', age: 18 }),
  (veselin:Person { name: 'Veselin', age: 20 }),
  (florentin)-[:KNOWS { since: 2010 }]->(adam),
  (florentin)-[:KNOWS { since: 2018 }]->(veselin)

Additionally, we will project a few graphs to the graph catalog, for more details see native projections and Cypher projections.

Project Person nodes and KNOWS relationships using native projections:
CALL gds.graph.project('personsNative', 'Person', 'KNOWS')
Project Person nodes and KNOWS relationships using Cypher projections:
CALL gds.graph.project.cypher(
  'personsCypher',
  'MATCH (n:Person) RETURN id(n) AS id, labels(n) as labels',
  'MATCH (n:Person)-[r:KNOWS]->(m:Person) RETURN id(n) AS source, id(m) AS target, type(r) as type')
Project Person nodes with property age and KNOWS relationships using Native projections:
CALL gds.graph.project(
  'personsWithAgeNative',
  {
    Person: {properties: 'age'}
  },
  'KNOWS'
)

2.1. List basic information about all graphs in the catalog

List basic information about all graphs in the catalog:
CALL gds.graph.list()
YIELD graphName, nodeCount, relationshipCount
RETURN graphName, nodeCount, relationshipCount
ORDER BY graphName ASC
Table 3. Results
graphName nodeCount relationshipCount

"personsCypher"

3

2

"personsNative"

3

2

"personsWithAgeNative"

3

2

2.2. List extended information about a specific named graph in the catalog

List extended information about a specific Cypher named graph in the catalog:
CALL gds.graph.list('personsCypher')
YIELD graphName, configuration
RETURN graphName, configuration.nodeQuery AS nodeQuery
Table 4. Results
graphName nodeQuery

"personsCypher"

"MATCH (n:Person) RETURN id(n) AS id, labels(n) as labels"
List extended information about a specific native named graph in the catalog:
CALL gds.graph.list('personsNative')
YIELD graphName, configuration
RETURN graphName, configuration.nodeProjection AS nodeProjection
Table 5. Results
graphName nodeProjection

"personsNative"

{Person={label=Person, properties={}}}

The above examples demonstrate that nodeQuery only has value when the graph is projected using Cypher projection while nodeProjection is present when we have a native graph. This is also true for relationshipQuery and relationshipProjection` respectively.

Despite different result columns being present for the different projections that we can use the Graph Schemas are the same, which is demonstrated in the example below.

Cypher graph schema:
CALL gds.graph.list('personsCypher')
YIELD graphName, schemaWithOrientation
Table 6. Results
graphName schemaWithOrientation

"personsCypher"

{graphProperties={}, relationships={KNOWS={properties={}, direction=DIRECTED}}, nodes={Person={}}}
Native graph schema:
CALL gds.graph.list('personsNative')
YIELD graphName, schemaWithOrientation
Table 7. Results
graphName schemaWithOrientation

"personsNative"

{graphProperties={}, relationships={KNOWS={properties={}, direction=DIRECTED}}, nodes={Person={}}}

2.3. Degree distribution of a specific graph

List information about the degree distribution of a specific graph:
CALL gds.graph.list('personsNative')
YIELD graphName, degreeDistribution;
Table 8. Results
graphName degreeDistribution

"personsNative"

{p99=2, min=0, max=2, mean=0.6666666666666666, p90=2, p50=0, p999=2, p95=2, p75=2}