Changeset View
Changeset View
Standalone View
Standalone View
docs/grpc-api.rst
Show First 20 Lines • Show All 181 Lines • ▼ Show 20 Lines | |||||
.. code-block:: console | .. code-block:: console | ||||
$ grpc_cli call localhost:50091 swh.graph.TraversalService.GetNode \ | $ grpc_cli call localhost:50091 swh.graph.TraversalService.GetNode \ | ||||
'swhid: "swh:1:ori:ffffffffffffffffffffffffffffffffffffffff"' | 'swhid: "swh:1:ori:ffffffffffffffffffffffffffffffffffffffff"' | ||||
Rpc failed with status code 3, error message: Unknown SWHID: swh:1:ori:ffffffffffffffffffffffffffffffffffffffff | Rpc failed with status code 3, error message: Unknown SWHID: swh:1:ori:ffffffffffffffffffffffffffffffffffffffff | ||||
$ grpc_cli call localhost:50091 swh.graph.TraversalService.GetNode \ | $ grpc_cli call localhost:50091 swh.graph.TraversalService.GetNode \ | ||||
'swhid: "invalidswhid"' | 'swhid: "invalidswhid"' | ||||
Rpc failed with status code 3, error message: malformed SWHID: swh:1:ori:ffffffffffffffffffffffffffffffffffffffff | Rpc failed with status code 3, error message: malformed SWHID: invalidswhid | ||||
Selecting returned fields with FieldMask | Selecting returned fields with FieldMask | ||||
---------------------------------------- | ---------------------------------------- | ||||
Many endpoints, including **GetNode**, contain a ``mask`` field of type | Many endpoints, including **GetNode**, contain a ``mask`` field of type | ||||
`FieldMask | `FieldMask | ||||
<https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/FieldMask.html>`_, | <https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/FieldMask.html>`_, | ||||
▲ Show 20 Lines • Show All 175 Lines • ▼ Show 20 Lines | .. code-block:: console | ||||
swhid: "swh:1:rev:0000000000000000000000000000000000000009" | swhid: "swh:1:rev:0000000000000000000000000000000000000009" | ||||
swhid: "swh:1:rev:0000000000000000000000000000000000000003" | swhid: "swh:1:rev:0000000000000000000000000000000000000003" | ||||
Limiting the traversal | Limiting the traversal | ||||
~~~~~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~ | ||||
To avoid using up too much memory or resources, a traversal can be limited | To avoid using up too much memory or resources, a traversal can be limited | ||||
in two different ways: | in three different ways: | ||||
- the ``max_depth`` attribute defines the maximum depth of the traversal. | - the ``max_depth`` attribute defines the maximum depth of the traversal. | ||||
- the ``max_edges`` attribute defines the maximum number of edges that can be | - the ``max_edges`` attribute defines the maximum number of edges that can be | ||||
fetched by the traversal. | fetched by the traversal. | ||||
- the ``max_matching_nodes`` attribute defines how many nodes matching the | |||||
given constraints (see :ref:`swh-graph-grpc-api-return-nodes`) may be | |||||
visited by the traversal before halting. | |||||
This is typically used to limit the number of results in leaves requests. | |||||
When these limits are reached, the traversal will simply stop. While these | When these limits are reached, the traversal will simply stop. While these | ||||
options have obvious use-cases for anti-abuse, they can also be semantically | options have obvious use-cases for anti-abuse, they can also be semantically | ||||
useful: for instance, specifying ``max_depth: 1`` will only return the | useful: for instance, specifying ``max_depth: 1`` will only return the | ||||
*neighbors* of the source node. | *neighbors* of the source node. | ||||
.. _swh-graph-grpc-api-return-nodes: | |||||
Filtering returned nodes | Filtering returned nodes | ||||
~~~~~~~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||||
In many cases, clients might not want to get all the traversed nodes in the | In many cases, clients might not want to get all the traversed nodes in the | ||||
response stream. With the ``return_nodes`` field (of type ``NodeFilter``), it | response stream. With the ``return_nodes`` field (of type ``NodeFilter``), it | ||||
is possible to specify various *criteria* for which nodes should be sent to the | is possible to specify various *criteria* for which nodes should be sent to the | ||||
stream. By default, all nodes are returned. | stream. By default, all nodes are returned. | ||||
▲ Show 20 Lines • Show All 128 Lines • ▼ Show 20 Lines | .. code-block:: console | ||||
swhid: "swh:1:dir:0000000000000000000000000000000000000006" | swhid: "swh:1:dir:0000000000000000000000000000000000000006" | ||||
swhid: "swh:1:dir:0000000000000000000000000000000000000008" | swhid: "swh:1:dir:0000000000000000000000000000000000000008" | ||||
swhid: "swh:1:dir:0000000000000000000000000000000000000012" | swhid: "swh:1:dir:0000000000000000000000000000000000000012" | ||||
swhid: "swh:1:rev:0000000000000000000000000000000000000013" | swhid: "swh:1:rev:0000000000000000000000000000000000000013" | ||||
swhid: "swh:1:rev:0000000000000000000000000000000000000018" | swhid: "swh:1:rev:0000000000000000000000000000000000000018" | ||||
swhid: "swh:1:dir:0000000000000000000000000000000000000017" | swhid: "swh:1:dir:0000000000000000000000000000000000000017" | ||||
swhid: "swh:1:dir:0000000000000000000000000000000000000016" | swhid: "swh:1:dir:0000000000000000000000000000000000000016" | ||||
swhid: "swh:1:cnt:0000000000000000000000000000000000000015" | swhid: "swh:1:cnt:0000000000000000000000000000000000000015" | ||||
middle_node_index: 5 | midpoint_index: 5 | ||||
Because ``middle_node_index = 5``, the common ancestor is | Because ``midpoint_index = 5``, the common ancestor is | ||||
``swh:1:rev:0000000000000000000000000000000000000018``. | ``swh:1:rev:0000000000000000000000000000000000000018``. | ||||
.. _swh-graph-grpc-api-protobuf: | .. _swh-graph-grpc-api-protobuf: | ||||
Protobuf API Reference | Protobuf API Reference | ||||
====================== | ====================== | ||||
Show All 9 Lines |