# Graph requests

Overview

The Blitz API offers several requests that are subclasses of GraphQuery. These may be submitted to the server for asynchronous processing of linked graphs of OMERO model objects. This section gives a brief overview of the graph requests and their purpose. Follow the links to see more details.

## Querying the model object graph

GraphQuery (base class)

  The parent of the requests below, it includes a `targetObjects` property that specifies from which model objects to start processing. The LegalGraphTargets request can be used to determine which types of model object may be targeted.

DiskUsage2

  Report on the disk usage of the target objects and their contents by type, user and group. Includes a `targetClasses` property to allow specifying every visible instance of a type.

FindParents

  Find the parents of the target objects, both direct and indirect. `typesOfParents` specifies the types of parents to report. `stopBefore` specifies types of model object to avoid in traversing the linked graph upward: those subgraphs are ignored unless otherwise reachable.

FindChildren

  Find the children of the target objects, both direct and indirect. `typesOfChildren` specifies the types of children to report. `stopBefore` specifies types of model object to avoid in traversing the linked graph downward: those subgraphs are ignored unless otherwise reachable.

## Changing the model object graph

GraphModify2 (base class)

  The parent of the requests below, it includes a `targetObjects` property that specifies from which model objects to start processing. The LegalGraphTargets request can be used to determine which types of model object may be targeted.

  The `childOptions` property lists how to process the contents of targeted objects.

  Because these requests change the data stored by the server, a `dryRun` property is provided that enables attempting to obtain the same response or error without actually making any changes.

ChildOption

  By default if a ‘child’ object is contained by a ‘parent’ targeted object then it is processed along with its parent if it is not also contained by another parent object that is not targeted. Use requests’ `childOptions` property to specify that children should be processed or not regardless of other parents.

  The `includeType` and `excludeType` properties specify for which types of children to override the behavior. For children that are annotations, the `includeNs` and `excludeNs` properties use the annotation namespace to limit the applicability of the override.

Chgrp2

  Change the group ID of the targeted objects and their contents. The objects are moved to the group specified by the `groupId` property.

Chown2

  Change the user ID of the targeted objects and their contents. The objects are given to the user specified by the `userId` property.

Chmod2

  Change the permissions for the targeted objects which must be groups. The `permissions` property specifies the new group type.

Delete2

  Delete the targeted objects and their contents. For original file instances the underlying file in the server’s binary repository may be deleted also.

Duplicate

  Duplicate a subgraph from the model object graph, starting from the targeted objects and recursing to their contents. The `typesToDuplicate`, `typesToReference`, `typesToIgnore` properties offer control over where in the graph traversal to stop duplicating and with what in the original graph to link the duplicate subgraph.

SkipHead

  Defer processing to start only at specific contents of the targeted objects. The `startFrom` property specifies the types of object to actually target with the processing and the `request` property, which may be any of the other requests from this section, specifies what to do to those objects once identified.

## Command-line interface

OMERO’s command-line interface client includes `chgrp`, `chown`, `delete` plugins that construct the corresponding `Chgrp2`, `Chown2`, `Delete2` requests. Additionally, the `group` plugin offers the `Chmod2` request and the `fs` plugin offers the `DiskUsage2` request.

## Request builders for Java

The Java gateway includes the Requests.java class which offers Java developers a set of builders that use method-chaining to allow convenient construction of new instances of the above requests.