You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@s2graph.apache.org by st...@apache.org on 2019/01/25 22:49:06 UTC
[14/20] incubator-s2graph git commit: update edge mutate
update edge mutate
Project: http://git-wip-us.apache.org/repos/asf/incubator-s2graph/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-s2graph/commit/aa309b22
Tree: http://git-wip-us.apache.org/repos/asf/incubator-s2graph/tree/aa309b22
Diff: http://git-wip-us.apache.org/repos/asf/incubator-s2graph/diff/aa309b22
Branch: refs/heads/master
Commit: aa309b220844280429841784a61e06cccafcd89d
Parents: c131990
Author: daewon <da...@apache.org>
Authored: Thu Dec 27 17:39:13 2018 +0900
Committer: daewon <da...@apache.org>
Committed: Thu Dec 27 17:39:13 2018 +0900
----------------------------------------------------------------------
doc/source/api/index.rst | 2 +-
doc/source/api/mutate/mutate_edge.rst | 54 +++++++++++++++++++-----------
2 files changed, 35 insertions(+), 21 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-s2graph/blob/aa309b22/doc/source/api/index.rst
----------------------------------------------------------------------
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
index df495ab..e74650a 100644
--- a/doc/source/api/index.rst
+++ b/doc/source/api/index.rst
@@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-API Glossary
+HTTP API Glossary
==============================================
The following is a non-exhaustive list of commonly used S2Graph APIs and their examples
http://git-wip-us.apache.org/repos/asf/incubator-s2graph/blob/aa309b22/doc/source/api/mutate/mutate_edge.rst
----------------------------------------------------------------------
diff --git a/doc/source/api/mutate/mutate_edge.rst b/doc/source/api/mutate/mutate_edge.rst
index 1e21079..553c8a1 100644
--- a/doc/source/api/mutate/mutate_edge.rst
+++ b/doc/source/api/mutate/mutate_edge.rst
@@ -13,19 +13,20 @@ The following fields need to be specified when inserting an edge, and are return
:header: "Field Name", "Definition", "Data Type", "Example", "Note"
:widths: 15, 30, 30, 30, 30
- "timestamp", "Issue time of request", "Long", "1430116731156", "Required. Unix Epoch time in milliseconds. S2Graph TTL and timestamp unit is milliseconds."
+ "**timestamp**", "Issue time of request", "Long", "1430116731156", "Required. Unix Epoch time in milliseconds. S2Graph TTL and timestamp unit is **milliseconds**"
"operation", "One of insert, delete, update, or increment", "String", "'i', 'insert'", "Required only for bulk operations. Aliases are also available: i (insert), d (delete), u (update), in (increment). Default is insert"
- "from", "Id of source vertex", "Long/String", "1", "Required. Use long if possible. Maximum string byte-size is 249"
- "to", "Id of target vertex", "Long/String", "101", "Required. Use long if possible. Maximum string byte-size is 249"
+ "from", "Id of source vertex", "Long/String", "1", "Required. Use long if possible. **Maximum string byte-size is 249**"
+ "to", "Id of target vertex", "Long/String", "101", "Required. Use long if possible. **Maximum string byte-size is 249**"
"label", "Label name", "String", "graph_test", "Required"
- "direction", "Direction of the edge. Should be one of out/ in/ undirected", "String", "out", "Required. Alias are also available: o (out), i (in), u (undirected)"
- "props", "Additional properties of the edge", "JSON (dictionary)", "{""timestamp"": 1417616431, ""affinity_score"":10, ""is_hidden"": false, ""is_valid"": true}", "Required. If in indexed properties isn't given, default values will be added"
+ "direction", "Direction of the edge. Should be one of **out/ in/ undirected**", "String", "out", "Required. Alias are also available: o (out), i (in), u (undirected)"
+ "props", "Additional properties of the edge", "JSON (dictionary)", "{""timestamp"": 1417616431, ""affinity_score"":10, ""is_hidden"": false, ""is_valid"": true}", "Required. **If in indexed properties isn't given, default values will be added**"
Basic Edge Operations
--------------------------
In S2Graph, an Edge supports five different operations.
+
- ``insert``: Create new edge.
- ``delete``: Delete existing edge.
- ``update``: Update existing edge`s state.
@@ -33,6 +34,7 @@ In S2Graph, an Edge supports five different operations.
- ``deleteAll``: Delete all adjacent edges from certain source vertex. (Available for strong consistency only)
Edge operations work differently depending on the target label`s consistency level.
+
For a better understanding, please take a look at the following test cases.
Create 2 different labels, one of each consistencyLevels.
@@ -56,7 +58,6 @@ Then insert a same set of edges to each labels and query them as follows.
Note that only one edge exist between (101, 10, s2graph_label_test, out).
-
.. code:: json
{
@@ -176,10 +177,15 @@ This time there are ``three edges`` between (101, 10, s2graph_label_test_weak, o
Strong Consistency
---------------------
-**Insert** - ``POST /mutate/edge/insert``
+Insert - ``POST /mutate/edge/insert``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
A unique edge is identified by a combination of (from, to, label, direction). For insert operations, S2Graph first checks if an edge with same (from, to, label, direction) information exists. If there is an existing edge, then insert will work as ``update``. See above example.
-**Delete** - ``POST /mutate/edge/delete``
+Delete - ``POST /mutate/edge/delete``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
For edge deletion, again, S2Graph looks for a unique edge with (from, to, label, direction). However, this time it checks the timestamp of the delete request and the existing edge. The timestamp on the delete request ``must be larger than that on the existing edge`` or else the request will be ignored. If everything is well, the edge will be deleted. Also note that no props information is necessary for a delete request on a strongly consistent label since there will be only one edge with edge`s unique id(from, to, label, direction).
.. code:: bash
@@ -189,7 +195,8 @@ For edge deletion, again, S2Graph looks for a unique edge with (from, to, label,
{"timestamp": 10, "from": 101, "to": 10, "label": "s2graph_label_test"}
]'
-**Update** - ``POST /mutate/edge/update``
+Update - ``POST /mutate/edge/update``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What an update operation does to a strongly consistent label is identical to an insert.
@@ -202,7 +209,8 @@ What an update operation does to a strongly consistent label is identical to an
]'
-**Increment** - ``POST /mutate/edge/increment``
+Increment - ``POST /mutate/edge/increment``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Works like update, other than it returns the incremented value and not the old value.
@@ -213,9 +221,10 @@ Works like update, other than it returns the incremented value and not the old v
{"timestamp": 10, "from": 101, "to": 10, "label": "s2graph_label_test", "props": {"time": 100, "weight": -10}}
]'
-**Delete All** - ``POST /mutate/edge/deleteAll``
+Delete All - ``POST /mutate/edge/deleteAll``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Delete all adjacent edges to the source vertex. **Please note that edges with both in and out directions will be deleted**
+Delete all adjacent edges to the source vertex. ``Please note that edges with both in and out directions will be deleted``
.. code:: bash
@@ -229,11 +238,13 @@ Weak Consistency
-----------------
-**Insert** ``POST /mutate/edge/insert``
+Insert ``POST /mutate/edge/insert``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-S2Graph **does not look** for a unique edge defined by (from, to, label, direction). It simply stores a new edge according to the request. No read, no consistency check. Note that this difference allows multiple edges with same (from, to, label, direction) id.
+S2Graph ``does not look`` for a unique edge defined by (from, to, label, direction). It simply stores a new edge according to the request. No read, no consistency check. Note that this difference allows multiple edges with same (from, to, label, direction) id.
-**Delete** - ``POST /graphs/edges/delete``
+Delete - ``POST /graphs/edges/delete``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For deletion on weakly consistent edges, first, S2Graph fetches existing edges from storage. Then, on each resulting edges, fires the actual delete operations.
@@ -294,15 +305,18 @@ For deletion on weakly consistent edges, first, S2Graph fetches existing edges f
}
]'
-**Update** - ``POST /mutate/edge/update``
+Update - ``POST /mutate/edge/update``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Like insert, S2Graph **does not check** for uniqueness. Update requires a pre-fetch of existing edges, similar to delete. Props of the resulting edges will be updated.
+Like insert, S2Graph ``does not check`` for uniqueness. Update requires a pre-fetch of existing edges, similar to delete. Props of the resulting edges will be updated.
-**Increment** - ``POST /mutate/edge/increment``
+Increment - ``POST /mutate/edge/increment``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For increment, S2Graph also **does not check** for uniqueness. Update requires a pre-fetch of existing edges, similar to delete. Props of the resulting edges will be incremented.
+For increment, S2Graph also ``does not check`` for uniqueness. Update requires a pre-fetch of existing edges, similar to delete. Props of the resulting edges will be incremented.
-**Delete All** - ``POST /mutate/edge/deleteAll``
+Delete All - ``POST /mutate/edge/deleteAll``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identical to strong consistency.