# Graph projections and catalogue

[Wiki](../README.md) / [Graph data science](README.md)

**On this page**

- [Graph catalogue](#graph-catalogue)
  - [Native projection estimates](#native-projection-estimates)

## Graph catalogue

These statements illustrate catalogue operations on existing `Person`/`KNOWS`
data. Run the [self-contained walkthrough](README.md#run-an-analysis) for a fresh
database. Keep the projection until you have finished the algorithm examples.

```cypher
CALL gds.graph.project('people', 'Person', {
  KNOWS: {orientation: 'UNDIRECTED', properties: ['weight']}
}, {nodeProperties: ['embedding']});
CALL gds.graph.list() YIELD graphName, nodeCount, relationshipCount;
CALL gds.graph.exists('people') YIELD exists;
```

`project(name, nodeProjection, relationshipProjection[, configuration])`
accepts a string, a list of strings or a map for either projection. `'*'`
selects all labels/types. Map entries can rename a label/type using `label` or
`type`; relationships support `NATURAL`, `REVERSE` and `UNDIRECTED` orientation.
Undirected projections contain an arc in each direction. Both map forms accept
`properties`; global `nodeProperties` and `relationshipProperties` are also
supported. Property definitions may rename fields and provide defaults:

```cypher
CALL gds.graph.project('weighted', '*', {
  KNOWS: {properties: {weight: {property: 'cost', defaultValue: 1.0}}}
});
```

Projected graphs are immutable snapshots until explicitly mutated. They belong
to one database, remain independent of subsequent live graph changes, consume
RAM and disappear on reopen. Project/drop/mutate participate in GDB statement
and explicit transaction rollback. Failed write-back rejects deleted nodes and
reused numeric node IDs. Reproject to analyse newly created data.

`list([name])` returns catalogue entries, `exists(name)` returns a boolean, and
`drop(name[, failIfMissing])` defaults to failing on an unknown graph.
For example, `CALL gds.graph.drop('people')` releases this projection after use.
`gds.graph.nodeProperty.stream(name, property)` returns `nodeId, propertyValue`.
`gds.graph.nodeProperties.write(name, properties)` copies projected properties
onto live nodes; `properties` can be a name or list of names.
`gds.util.asNode(id)` and `gds.util.asNodes(ids)` resolve live node values.

Native projection is implemented; Cypher aggregation/query projections,
catalogue persistence and model/pipeline catalogues are
not included.

### Native projection estimates

```cypher
CALL gds.graph.project.estimate('Person', {
  KNOWS: {orientation:'UNDIRECTED', properties:['weight']}
}, {nodeProperties:['embedding']})
YIELD nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory;
```

The arguments are node projection, relationship projection and optional
configuration; **no graph name** is supplied. This read-only scan uses the same
selection/property rules as native projection, including aliasing and doubled
undirected arcs. It retains selected IDs but does not create a catalogue entry
or allocate a complete projected graph. Memory ranges are planning estimates,
not allocator measurements or reservations.

## Related articles

[GDS algorithms and execution modes](algorithms.md) · [GDS resources and cancellation](resources.md) · [Graph data science](README.md)
