|
1 | 1 | # Node |
2 | 2 |
|
3 | | -Nodes are entities which contain the following attributes: |
4 | | - |
5 | | -- **NodeLabels**: Zero or more node labels, usually one. They are basically strings with validation. They must be |
6 | | - CamelCase as per [Neo4j's documentation](https://neo4j.com/docs/cypher-manual/current/syntax/naming/#_recommendations) |
7 | | - . |
8 | | - Node labels can start with a single underscore, although this is reserved for internal logic. |
9 | | - You can overwrite the validation part by creating your own implementation of |
10 | | - `Syndesi\CypherDataStructures\Contract\NodeLabelInterface`. |
11 | | - |
12 | | -- **Properties**: Zero or more properties, which are composed of one `PropertyName` for the key and a mixed property value. |
13 | | - Within the node they are stored as an array-like storage. For more information see [property](property.md). |
14 | | - |
15 | | -- **Identifiers**: The names of zero or more properties which uniquely identify the node. The referenced properties must |
16 | | - contain a value. |
17 | | - When removing identifying properties without removing the identifier first, an exception is triggered. |
18 | | - |
19 | | -- **Relations**: A list of relations which either start or end at the node. |
20 | | - The default implementation stores relations in [weak references](https://www.php.net/manual/en/class.weakreference.php) |
21 | | - so when a relation is unset, the node's relation will become `null`. This is done to remove the possibility of cyclic |
22 | | - references. |
23 | | - Relations must contain the node itself as either the start or end node. |
24 | | - |
25 | | -!> **Note**: Make sure that identifying elements (node labels, relation type, identifying properties) are set before |
26 | | - referencing nodes to relations and vice versa. |
27 | | - Changing those elements later does not update the existing references. |
28 | | - |
29 | | -## Examples |
| 3 | +Nodes are the most basic data elements within a graph database. |
| 4 | +They can be created as following: |
30 | 5 |
|
31 | 6 | ```php |
32 | | -use Syndesi\CypherDataStructures\Type\NodeLabel; |
33 | 7 | use Syndesi\CypherDataStructures\Type\Node; |
34 | | -use Syndesi\CypherDataStructures\Type\PropertyName; |
35 | 8 |
|
36 | 9 | $node = new Node(); |
37 | | -$node |
38 | | - ->addNodeLabel(new NodeLabel("SomeNode")) |
39 | | - ->addProperty(new PropertyName("id"), 1234) |
40 | | - ->addIdentifier(new PropertyName("id")); |
| 10 | +``` |
| 11 | + |
| 12 | +## Labels |
| 13 | + |
| 14 | +Labels identify the node's type, e.g. a label called `User` would identify a node as a user and `Document` would |
| 15 | +identify it as a document. |
| 16 | +Nodes can have zero, one or more labels, although one label is the default. |
| 17 | +Labels [should be written in CamelCase](https://neo4j.com/docs/cypher-manual/current/syntax/naming/#_recommendations). |
| 18 | + |
| 19 | +```php |
| 20 | +// add a single label to a node: |
| 21 | +$node->addLabel('FirstLabel'); |
| 22 | + |
| 23 | +// add multiple labels to a node: |
| 24 | +$node->addLabels(['SecondLabel', 'ThirdLabel']); |
| 25 | + |
| 26 | +// check if a node has a label: |
| 27 | +$node->hasLabel('FirstLabel'); |
| 28 | + |
| 29 | +// get all labels from a node: |
| 30 | +$node->getLabels(); |
| 31 | + |
| 32 | +// remove a label from a node: |
| 33 | +$node->removeLabel('ThirdLabel'); |
| 34 | + |
| 35 | +// remove all labels from a node: |
| 36 | +$node->removeLabels(); |
| 37 | +``` |
| 38 | + |
| 39 | +## Properties |
| 40 | + |
| 41 | +Properties are key-value-pairs which can store data within a node. |
| 42 | +The keys must be unique and [should be written in camelCase](https://neo4j.com/docs/cypher-manual/current/styleguide/#cypher-styleguide-casing). |
| 43 | + |
| 44 | +!> **Note**: While this library supports arrays and objects as property values, Neo4j has limited support for those types. |
| 45 | + Be sure that those types are correctly handled. |
| 46 | + |
| 47 | +```php |
| 48 | +// add property to a node: |
| 49 | +$node->addProperty('propertyName', 'property value'); |
| 50 | + |
| 51 | +// add multiple properties to a node: |
| 52 | +$node->addProperties([ |
| 53 | + 'id' => 123, |
| 54 | + 'hello' => 'world :D' |
| 55 | +]); |
| 56 | + |
| 57 | +// check if a node has a specific property: |
| 58 | +$node->hasProperty('id'); |
| 59 | + |
| 60 | +// get the value of a specific property: |
| 61 | +$node->getProperty('id'); |
| 62 | + |
| 63 | +// get all properties from a node: |
| 64 | +$node->getProperties(); |
| 65 | + |
| 66 | +// remove a specific property from a node: |
| 67 | +$node->removeProperty('hello'); |
| 68 | + |
| 69 | +// remove all properties from a node: |
| 70 | +$node->removeProperties(); |
| 71 | +``` |
| 72 | + |
| 73 | +### Identifying Properties |
| 74 | + |
| 75 | +Identifying properties are just normal properties which are marked to identify the node uniquely within the database. |
| 76 | + |
| 77 | +!> **Note**: Identifying properties are not part of the OpenCypher specification. |
| 78 | + |
| 79 | +!> **Important**: Only existing properties can be marked as "identifying". Also, identifying properties can not be removed |
| 80 | + from the node as long as the identifying-mark is not removed. |
| 81 | + |
| 82 | +```php |
| 83 | +// add identifying property to a node: |
| 84 | +$node->addProperty('id', 123); |
| 85 | +$node->addIdentifier('id'); |
| 86 | + |
| 87 | +// add multiple identifying properties to a node: |
| 88 | +$node->addProperties([ |
| 89 | + 'id2' => '234', |
| 90 | + 'id3' => '345' |
| 91 | +]); |
| 92 | +$node->addIdentifiers(['id2', 'id3']); |
| 93 | + |
| 94 | +// check if node has a specific identifying property: |
| 95 | +$node->hasIdentifier('id'); |
| 96 | + |
| 97 | +// get the value of a specific identifying property: |
| 98 | +$node->getIdentifier('id'); |
| 99 | + |
| 100 | +// get all identifying properties: |
| 101 | +$node->getIdentifiers(); |
| 102 | + |
| 103 | +// remove a specific identifying property mark without removing the property itself: |
| 104 | +$node->removeIdentifier('id'); |
| 105 | + |
| 106 | +// remove all identifying property marks without removing the properties themselves: |
| 107 | +$node->removeProperties(); |
| 108 | +``` |
| 109 | + |
| 110 | +## Relations |
| 111 | + |
| 112 | +Nodes can relate to other nodes and are connected to them via [relations](relation.md). Those must either start or end |
| 113 | +at the current node. |
| 114 | + |
| 115 | +```php |
| 116 | +$node = new \Syndesi\CypherDataStructures\Type\Node(); |
| 117 | +use Syndesi\CypherDataStructures\Type\Relation; |
| 118 | + |
| 119 | +$relation = new Relation(); |
| 120 | +$relation->setStartNode($node); // important: Relations must either start or end at the node itself |
| 121 | +$relation->setType('RELATION'); |
| 122 | + |
| 123 | +// add relation to node: |
| 124 | +$node->addRelation($relation); |
| 125 | + |
| 126 | +// add relations to node: |
| 127 | +$node->addRelations([ |
| 128 | + $relation, |
| 129 | + clone $relation |
| 130 | +]); |
| 131 | + |
| 132 | +// check if a node has a specific relation |
| 133 | +$node->hasRelation($relation); |
| 134 | + |
| 135 | +// get all relations from a node |
| 136 | +$node->getRelations(); |
| 137 | + |
| 138 | +// remove a specific relation from a node: |
| 139 | +$node->removeRelation($relation); |
| 140 | + |
| 141 | +// remove all relations from a node: |
| 142 | +$node->removeRelations(); |
41 | 143 | ``` |
0 commit comments