Add IO Reference docs IO Reference docs provide more details and samples for GraphML, Gryo and GraphSON.
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/f04807b9 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/f04807b9 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/f04807b9 Branch: refs/heads/TINKERPOP-1487 Commit: f04807b942ff797d3ab04a284f7413d5f45e94c4 Parents: 233a6ba Author: Stephen Mallette <[email protected]> Authored: Tue Oct 4 12:19:39 2016 -0400 Committer: Stephen Mallette <[email protected]> Committed: Tue Oct 4 12:19:39 2016 -0400 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 1 + docs/src/dev/io/graphml.asciidoc | 119 + docs/src/dev/io/graphson.asciidoc | 4586 ++++++++++++++++++ docs/src/dev/io/gryo.asciidoc | 63 + docs/src/dev/io/index.asciidoc | 37 + docs/src/dev/provider/index.asciidoc | 4 + docs/src/index.asciidoc | 2 + .../upgrade/release-3.2.x-incubating.asciidoc | 10 +- docs/static/images/gremlin-io2.png | Bin 0 -> 185756 bytes .../structure/io/graphson/GraphSONModule.java | 2 +- pom.xml | 25 + .../structure/TinkerIoRegistryV2d0.java | 2 +- 12 files changed, 4848 insertions(+), 3 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/f04807b9/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index ade43cd..ff295ee 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -45,6 +45,7 @@ TinkerPop 3.2.3 (Release Date: NOT OFFICIALLY RELEASED YET) * `SubgraphStrategy` now supports vertex property filtering. * Fixed a bug in Gremlin-Python `P` where predicates reversed the order of the predicates. * Added tests to `DedupTest` for the `dedup(Scope, String...)` overload. +* Added more detailed reference documentation for IO formats. * Fixed a bug in serialization of `Lambda` instances in GraphSON, which prevented their use in remote traversals. * Fixed a naming bug in Gremlin-Python where `P._and` and `P._or` should be `P.and_` and `P.or_`. (*breaking*) * `where()` predicate-based steps now support `by()`-modulation. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/f04807b9/docs/src/dev/io/graphml.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/io/graphml.asciidoc b/docs/src/dev/io/graphml.asciidoc new file mode 100644 index 0000000..89eb0da --- /dev/null +++ b/docs/src/dev/io/graphml.asciidoc @@ -0,0 +1,119 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// +[[graphml]] +GraphML +======= + +image:gremlin-graphml.png[width=350,float=left] The link:http://graphml.graphdrawing.org/[GraphML] file format is a +common XML-based representation of a graph. It uses an edge list format where vertices and their properties are listed +and edges and their properties are listed by referencing the in and out vertices for each edge. GraphML does support a +number of features which are not implemented by TinkerPop (e.g. extending GraphML with custom types) and there are +features of TinkerPop that are not supported by GraphML (e.g. meta-properties), but GraphML does represent the most +universal way to consume or produce a graph for integration with other systems as GraphML tends to have fairly wide +support. + +In TinkerPop, GraphML is also not extended for purpose of serializing just any type (i.e. serialize just a `Vertex` to +XML). It is only supported for a `Graph` instance. + +The following example is a representation of the Modern toy graph in GraphML: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<graphml xmlns="http://graphml.graphdrawing.org/xmlns"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.1/graphml.xsd";> + <key id="labelV" for="node" attr.name="labelV" attr.type="string" /> + <key id="name" for="node" attr.name="name" attr.type="string" /> + <key id="lang" for="node" attr.name="lang" attr.type="string" /> + <key id="age" for="node" attr.name="age" attr.type="int" /> + <key id="labelE" for="edge" attr.name="labelE" attr.type="string" /> + <key id="weight" for="edge" attr.name="weight" attr.type="double" /> + <graph id="G" edgedefault="directed"> + <node id="1"> + <data key="labelV">person</data> + <data key="name">marko</data> + <data key="age">29</data> + </node> + <node id="2"> + <data key="labelV">person</data> + <data key="name">vadas</data> + <data key="age">27</data> + </node> + <node id="3"> + <data key="labelV">software</data> + <data key="name">lop</data> + <data key="lang">java</data> + </node> + <node id="4"> + <data key="labelV">person</data> + <data key="name">josh</data> + <data key="age">32</data> + </node> + <node id="5"> + <data key="labelV">software</data> + <data key="name">ripple</data> + <data key="lang">java</data> + </node> + <node id="6"> + <data key="labelV">person</data> + <data key="name">peter</data> + <data key="age">35</data> + </node> + <edge id="7" source="1" target="2"> + <data key="labelE">knows</data> + <data key="weight">0.5</data> + </edge> + <edge id="8" source="1" target="4"> + <data key="labelE">knows</data> + <data key="weight">1.0</data> + </edge> + <edge id="9" source="1" target="3"> + <data key="labelE">created</data> + <data key="weight">0.4</data> + </edge> + <edge id="10" source="4" target="5"> + <data key="labelE">created</data> + <data key="weight">1.0</data> + </edge> + <edge id="11" source="4" target="3"> + <data key="labelE">created</data> + <data key="weight">0.4</data> + </edge> + <edge id="12" source="6" target="3"> + <data key="labelE">created</data> + <data key="weight">0.2</data> + </edge> + </graph> +</graphml> +---- + +Consider the following points when reading a GraphML file to TinkerPop that was generated outside of TinkerPop: + +* Supports the following values in `attr.type`: +** `string` +** `float` +** `double` +** `int` +** `long` +** `boolean` +* Does not currently support the `<default>` tag in the schema definitions. +* The GraphML will be read as a directed graph regardless of the value supplied `edgedefault` setting in the `<graph>` +tag as that is the nature of the type of graph that TinkerPop supports. +* The vertex and edge `id` values will always be treated as a `String` if the `Graph` instance consuming the data +supports user-supplied identifiers (i.e. TinkerGraph). +* By default the labels for vertex and edges are referred to as "labelV" and "labelE" respectively. It is possible to +change these defaults on the `Builder` for the `GraphReader`. If no label is supplied, the reader will default to +"vertex" and "edge" respectively as is the general expectation in TinkerPop when those values are omitted. \ No newline at end of file
