Listing graphs

This section details how to list graphs stored in the graph catalog of the Neo4j Graph Data Science library.

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,
  nodeProjection: Map,
  relationshipProjection: Map,
  nodeQuery: String,
  relationshipQuery: String,
  nodeFilter: String,
  relationshipFilter: String,
  nodeCount: Integer,
  relationshipCount: Integer,
  schema: 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 created.

nodeProjection

Map

Node projection used to create the graph. If a Cypher projection was used, this will be a derived node projection.

relationshipProjection

Map

Relationship projection used to create the graph. If a Cypher projection was used, this will be a derived relationship projection.

nodeQuery

String

Node query used to create the graph. If a native projection was used, this will be null.

relationshipQuery

String

Relationship query used to create the graph. If a native projection was used, this will be null.

nodeFilter

String

The node filter used when creating this subgraph from another in-memory graph. If the graph has been created from Neo4j, this will be null.

relationshipFilter

String

The relationship filter used when creating this subgraph from another in-memory graph. If the graph has been created from Neo4j, this will be null.

nodeCount

Integer

Number of nodes in the graph.

relationshipCount

Integer

Number of relationships in the graph.

schema

Map

Node labels, Relationship types and properties contained in the in-memory graph.

degreeDistribution

Map

Histogram of degrees in the graph.

density

Float

Density of the graph.

creationTime

Datetime

Time when the graph was created.

modificationTime

Datetime

Time when the graph was last modified.

sizeInBytes

Integer

Number of bytes used in the Java heap to store the graph.

memoryUsage

String

Human readable description of sizeInBytes.

The information contains basic statistics about the graph, e.g., the node and relationship count. The result field creationTime indicates when the graph was created 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 created on. Referring to a named graph in a procedure is only allowed on the database it has been created 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 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.create('personsNative', 'Person', 'KNOWS')
Project Person nodes and KNOWS relationships using Cypher projections:
CALL gds.graph.create.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.create(
  '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, nodeProjection, nodeQuery
Table 4. Results
graphName nodeProjection nodeQuery

"personsCypher"

null

"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, nodeProjection, nodeQuery
Table 5. Results
graphName nodeProjection nodeQuery

"personsNative"

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

null

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, schema
Table 6. Results
graphName schema

"personsCypher"

{relationships={KNOWS={}}, nodes={Person={}}}

Native graph schema:
CALL gds.graph.list('personsNative')
YIELD graphName, schema
Table 7. Results
graphName schema

"personsNative"

{relationships={KNOWS={}}, 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=0}