Labels

Labels are arbitrary tags that can be applied to nodes, to aid in querying and type hinting in an application. A label marks a node as being part of a specific set of nodes.

Managing Labels

Labels can be easily generated by passing a label name to the Client::makeLabel method. The name can be any non-empty string or numeric value (numeric values are cast to strings.) Using an empty value, or any non-string/non-numeric value will result in an Exception being thrown.

$label = $client->makeLabel('MyLabel');

The Client::makeLabel method returns a Label object, which can be added to or removed from a Node object. It is important to note that the label will not exist on the database server until it has been added to at least one node.

All labels on the server can be listed with the Client::getLabels method. The method can also be given a specific node to only return labels on that node.

$allLabels = $client->getLabels();

$node = $client->getNode(123);
$nodeLabels = $client->getLabels($node);

Client::getLabels returns an array of Label objects.

Adding Labels to a Node

A set of labels can be added to a node using the Node::addLabels method. The method takes an array of one or more Label objects (passing in an empty array will result in an error.)

$node = $client->getNode(123);
$myLabel = $client->makeLabel('MyLabel');
$myOtherLabel = $client->makeLabel('MyOtherLabel');

$labels = $node->addLabels(array($myLabel, $myOtherLabel));

When the labels are successfully added, $labels will be an array of Label objects representing all the labels on the node, including the ones that were just added and any that were already set on the node. In the example above, $labels will contain 2 labels: "MyLabel" and "MyOtherLabel".

Additional labels can be added the same way:

// Continuing from the example above
$oneMoreLabel = $client->makeLabel('Foobar');

$labels = $node->addLabels(array($oneMoreLabel));

$labels will now contain 3 labels: the two from before, and the new 'Foobar' label.

To get a list of all the labels on a node, use the Node::getLabels method:

$labels = $node->getLabels();

Removing Labels from a Node

Labels are removed from a node using the Node::removeLabels method. It follows the same syntax as adding a node, and the return value is the list of all remaining labels on the node, after the given labels have been removed.

$remainingLabels = $node->removeLabels(array($myLabel, $oneMoreLabel));

Querying with Labels

It is possible to get all the nodes having given label using Label::getNodes

$label = $client->makeLabel('MyLabel');

$nodes = $label->getNodes();

The return value is a result Row object, which can be iterated over like an array.

Sometimes, it is useful to get only a subset of the nodes tagged with a label that match a specific property value. The property name and value can be passed to Label::getNodes to limit the nodes that are returned.

// Only return nodes that have "Arthur" as the value of the firstName property
$nodes = $label->getNodes("firstName", "Arthur");