Graph

Graph object

class graphscope.framework.graph.Graph(session, incoming_data=None, oid_type='int64', directed=True, generate_eid=True)[source]

A class for representing metadata of a graph in the GraphScope.

A Graph object holds the metadata of a graph, such as key, schema, and the graph is directed or not.

It is worth noting that the graph is stored by the backend such as Analytical Engine, Vineyard. In other words, the graph object holds nothing but metadata.

The following example demonstrates its usage:

>>> import graphscope as gs
>>> from graphscope.framework.loader import Loader
>>> sess = gs.session()
>>> graph = sess.g()
>>> graph = graph.add_vertices("person.csv","person")
>>> graph = graph.add_vertices("software.csv", "software")
>>> graph = graph.add_edges("knows.csv", "knows", src_label="person", dst_label="person")
>>> graph = graph.add_edges("created.csv", "created", src_label="person", dst_label="software")
>>> print(graph)
>>> print(graph.schema)
__init__(session, incoming_data=None, oid_type='int64', directed=True, generate_eid=True)[source]

Construct a Graph object.

Parameters

  • session_id (str) – Session id of the session the graph is created in.

  • incoming_data –

    Graph can be initialized through various type of sources, which can be one of:

    • Operation

    • nx.Graph

    • Graph

    • vineyard.Object, vineyard.ObjectId or vineyard.ObjectName

add_column(results, selector)[source]

Add the results as a column to the graph. Modification rules are given by the selector.

Parameters

  • results (Context) – A Context that created by doing a query.

  • selector (dict) – Select results to add as column. Format is similar to selectors in Context

Returns

A new Graph with new columns.

Return type

Graph

add_edges(edges, label='_', properties=None, src_label=None, dst_label=None, src_field=0, dst_field=1)[source]

Add edges to graph. 1. Add edges to a uninitialized graph.

  1. src_label and dst_label both unspecified. In this case, current graph must has 0 (we deduce vertex label from edge table, and set vertex label name to ‘_’), or 1 vertex label (we set src_label and dst label to this).

  2. src_label and dst_label both specified and existed in current graph’s vertex labels.

  3. src_label and dst_label both specified and there is no vertex labels in current graph. we deduce all vertex labels from edge tables. Note that you either provide all vertex labels, or let graphscope deduce all vertex labels. We don’t support mixed style.

  1. Add edges to a existed graph.

    Must add a new kind of edge label, not a new relation to builded graph. But you can add a new relation to uninitialized part of the graph. src_label and dst_label must be specified and existed in current graph.

Parameters

  • edges (Union[str, Loader]) – Edge data source.

  • label (str, optional) – Edge label name. Defaults to “_”.

  • properties (list[str], optional) – List of column names loaded as properties. Defaults to None.

  • src_label (str, optional) – Source vertex label. Defaults to None.

  • dst_label (str, optional) – Destination vertex label. Defaults to None.

  • src_field (int, optional) – Column index or name used as src field. Defaults to 0.

  • dst_field (int, optional) – Column index or name used as dst field. Defaults to 1.

Raises

ValueError – If the given value is invalid or conflict with current graph.

Returns

A new graph with edge added, not yet evaluated.

Return type

Graph

detach()[source]

Detaching a graph makes it being left in vineyard even when the varaible for this Graph object leaves the lexical scope.

The graph can be accessed using the graph’s ObjectID or its name later.

property graph_type

The type of the graph object.

Returns

the type of the graph.

Return type

type (types_pb2.GraphType)

property key

The key of the corresponding graph in engine.

classmethod load_from(path, sess, **kwargs)[source]

Construct a Graph by deserialize from path. It will read all serialization files, which is dumped by Graph.serialize. If any serialize file doesn’t exists or broken, will error out.

Parameters

  • path (str) – Path contains the serialization files.

  • sess (graphscope.Session) – The target session that the graph will be construct in

Returns

A new graph object. Schema and data is supposed to be

identical with the one that called serialized method.

Return type

Graph

save_to(path, **kwargs)[source]

Serialize graph to a location. The meta and data of graph is dumped to specified location, and can be restored by Graph.deserialize in other sessions.

Each worker will write a path_{worker_id}.meta file and a path_{worker_id} file to storage. :param path: supported storages are local, hdfs, oss, s3 :type path: str

property schema

Schema of the graph.

Returns

the schema of the graph

Return type

GraphSchema

property schema_path

Path that Coordinator will write interactive schema path to.

Returns

The path contains the schema. for interactive engine.

Return type

str

property session_id

Get the currrent session_id.

Returns

Return session id that the graph belongs to.

Return type

str

to_dataframe(selector, vertex_range=None)[source]

Select some elements of the graph and output as a pandas.DataFrame

Parameters

  • selector (dict) – Select some portions of graph.

  • vertex_range (dict, optional) – Slice vertices. Defaults to None.

Returns

pandas.DataFrame

to_numpy(selector, vertex_range=None)[source]

Select some elements of the graph and output to numpy.

Parameters

  • selector (str) – Select a portion of graph as a numpy.ndarray.

  • vertex_range (dict, optional) – Slice vertices. Defaults to None.

Returns

numpy.ndarray

unload()[source]

Unload this graph from graphscope engine.

property vineyard_id

Get the vineyard object_id of this graph.

Returns

return vineyard id of this graph

Return type

str

Loader object

class graphscope.framework.loader.Loader(source, delimiter=',', header_row=True, **kwargs)[source]

Generic data source wrapper. Loader can take various data sources, and assemble necessary information into a AttrValue.

__init__(source, delimiter=',', header_row=True, **kwargs)[source]

Initialize a loader with configurable options. Note: Loader cannot be reused since it may change inner state when constructing information for loading a graph.

Parameters

  • source (str or value) –

    The data source to be load, which could be one of the followings:

    • local file: specified by URL file://...

    • oss file: specified by URL oss://...

    • hdfs file: specified by URL hdfs://...

    • s3 file: specified by URL s3://...

    • numpy ndarray, in CSR format

    • pandas dataframe

    Ordinary data sources can be loaded using vineyard stream as well, a vineyard:// prefix can be used in the URL then the local file, oss object or HDFS file will be loaded into a vineyard stream first, then GraphScope’s fragment will be built upon those streams in vineyard.

    Once the stream IO in vineyard reaches a stable state, it will be the default mode to load data sources and construct fragments in GraphScope.

  • delimiter (char, optional) – Column delimiter. Defaults to ‘,’

  • header_row (bool, optional) – Whether source have a header. If true, column names will be read from the first row of source, else they are named by ‘f0’, ‘f1’, …. Defaults to True.

Notes

Data is resolved by drivers in libvineyard . See more additional info in Loading Graph section of Docs, and implementations in libvineyard.

Graph Functions

graphscope.framework.graph_builder.load_from(edges: Union[Mapping[str, Union[graphscope.framework.loader.Loader, str, Sequence[numpy.ndarray], pandas.core.frame.DataFrame, vineyard.Object, vineyard.ObjectID, vineyard.ObjectName, Sequence, Mapping]], graphscope.framework.loader.Loader, str, Sequence[numpy.ndarray], pandas.core.frame.DataFrame, vineyard.Object, vineyard.ObjectID, vineyard.ObjectName, Sequence], vertices: Optional[Union[Mapping[str, Union[graphscope.framework.loader.Loader, str, Sequence[numpy.ndarray], pandas.core.frame.DataFrame, vineyard.Object, vineyard.ObjectID, vineyard.ObjectName, Sequence, Mapping]], graphscope.framework.loader.Loader, str, Sequence[numpy.ndarray], pandas.core.frame.DataFrame, vineyard.Object, vineyard.ObjectID, vineyard.ObjectName, Sequence]] = None, directed=True, oid_type='int64_t', generate_eid=True) → graphscope.framework.graph.Graph[source]

Load a Arrow property graph using a list of vertex/edge specifications.

Deprecated since version version: 0.3 Use graphscope.Graph() instead.

  • Use Dict of tuples to setup a graph.

    We can use a dict to set vertex and edge configurations, which can be used to build graphs.

    Examples:

    g = graphscope_session.load_from(
    edges={
        "group": [
            (
                "file:///home/admin/group.e",
                ["group_id", "member_size"],
                ("leader_student_id", "student"),
                ("member_student_id", "student"),
            ),
            (
                "file:///home/admin/group_for_teacher_student.e",
                ["group_id", "group_name", "establish_date"],
                ("teacher_in_charge_id", "teacher"),
                ("member_student_id", "student"),
            ),
        ]
    },
    vertices={
        "student": (
            "file:///home/admin/student.v",
            ["name", "lesson_nums", "avg_score"],
            "student_id",
        ),
        "teacher": (
            "file:///home/admin/teacher.v",
            ["name", "salary", "age"],
            "teacher_id",
        ),
    },
)

    ‘e’ is the label of edges, and ‘v’ is the label for vertices, edges are stored in the ‘both_in_out’ format edges with label ‘e’ linking from ‘v’ to ‘v’.

  • Use Dict of dict to setup a graph.

    We can also give each element inside the tuple a meaningful name, makes it more understandable.

    Examples:

    g = graphscope_session.load_from(
    edges={
        "group": [
            {
                "loader": "file:///home/admin/group.e",
                "properties": ["group_id", "member_size"],
                "source": ("leader_student_id", "student"),
                "destination": ("member_student_id", "student"),
            },
            {
                "loader": "file:///home/admin/group_for_teacher_student.e",
                "properties": ["group_id", "group_name", "establish_date"],
                "source": ("teacher_in_charge_id", "teacher"),
                "destination": ("member_student_id", "student"),
            },
        ]
    },
    vertices={
        "student": {
            "loader": "file:///home/admin/student.v",
            "properties": ["name", "lesson_nums", "avg_score"],
            "vid": "student_id",
        },
        "teacher": {
            "loader": "file:///home/admin/teacher.v",
            "properties": ["name", "salary", "age"],
            "vid": "teacher_id",
        },
    },
)
Parameters

  • edges – Edge configuration of the graph

  • vertices (optional) – Vertices configurations of the graph. Defaults to None. If None, we assume all edge’s src_label and dst_label are deduced and unambiguous.

  • directed (bool, optional) – Indicate whether the graph should be treated as directed or undirected.

  • oid_type (str, optional) – ID type of graph. Can be “int64_t” or “string”. Defaults to “int64_t”.

  • generate_eid (bool, optional) – Whether to generate a unique edge id for each edge. Generated eid will be placed in third column. This feature is for cooperating with interactive engine. If you only need to work with analytical engine, set it to False. Defaults to False.