diff --git a/antora.yml b/antora.yml index eb2a6c6..445586e 100644 --- a/antora.yml +++ b/antora.yml @@ -1,16 +1,16 @@ name: pytigergraph title: pyTigerGraph -version: 1.4 -display_version: "1.4" +version: 1.5 +display_version: "1.5" start_page: intro:index.adoc nav: - modules/intro/nav.adoc - modules/getting-started/nav.adoc -- modules/authentication/nav.adoc - modules/core-functions/nav.adoc - modules/gds/nav.adoc - modules/datasets/nav.adoc - modules/visualization/nav.adoc +- modules/object_oriented_schema/nav.adoc - modules/contributing/nav.adoc - modules/release-notes/nav.adoc diff --git a/generator/docstring2asciidoc_cfg_template.json b/generator/docstring2asciidoc_cfg_template.json index b8bd751..3cf9fd2 100644 --- a/generator/docstring2asciidoc_cfg_template.json +++ b/generator/docstring2asciidoc_cfg_template.json @@ -13,6 +13,7 @@ "pyTigerGraph/pyTigerGraphUDT.py": "modules/core-functions/pages/udt.adoc", "pyTigerGraph/pyTigerGraphUtils.py": "modules/core-functions/pages/utils.adoc", "pyTigerGraph/pyTigerGraphVertex.py": "modules/core-functions/pages/vertex.adoc", + "pyTigerGraph/schema.py": "modules/object_oriented_schema/pages/schema-def.adoc", "pyTigerGraph/gds/gds.py": "modules/gds/pages/gds.adoc", "pyTigerGraph/gds/dataloaders.py": "modules/gds/pages/dataloaders.adoc", "pyTigerGraph/gds/featurizer.py": "modules/gds/pages/featurizer.adoc", diff --git a/modules/core-functions/pages/base.adoc b/modules/core-functions/pages/base.adoc index f8ca688..541377f 100644 --- a/modules/core-functions/pages/base.adoc +++ b/modules/core-functions/pages/base.adoc @@ -18,14 +18,12 @@ a self-signed certificate will be used. * `graphname`: The default graph for running queries. * `gsqlSecret`: The secret key for GSQL. + See https://docs.tigergraph.com/tigergraph-server/current/user-access/managing-credentials#_secrets.[this] for more details. -Required for GSQL authentication on TigerGraph Cloud instances created after -July 5, 2022. * `username`: The username on the TigerGraph server. * `password`: The password for that user. * `tgCloud`: Set to `True` if using TigerGraph Cloud. If your hostname contains `tgcloud`, then this is automatically set to `True`, and you do not need to set this argument. * `restppPort`: The port for REST++ queries. -* `gsPort`: The port of all other queries. +* `gsPort`: The port for gsql server. * `gsqlVersion`: The version of the GSQL client to be used. Effectively the version of the database being connected to. * `version`: DEPRECATED; use `gsqlVersion`. diff --git a/modules/datasets/pages/dataset_object.adoc b/modules/datasets/pages/dataset_object.adoc index d191783..ba7f086 100644 --- a/modules/datasets/pages/dataset_object.adoc +++ b/modules/datasets/pages/dataset_object.adoc @@ -11,7 +11,10 @@ Stock datasets. Please see https://tigergraph-public-data.s3.us-west-1.amazonaws.com/inventory.json[this link] for datasets that are currently available. The files for the dataset with `name` will be -downloaded to local `tmp_dir` automatically when this class is instantiated. +downloaded to local `tmp_dir` automatically when this class is instantiated. +For offline environments, download the desired .tar manually from the inventory page, and extract in the desired location. +Specify the `tmp_dir` parameter to point to where the unzipped directory resides. + [discrete] ==== Parameters: diff --git a/modules/gds/pages/featurizer.adoc b/modules/gds/pages/featurizer.adoc index d249410..d2c98b6 100644 --- a/modules/gds/pages/featurizer.adoc +++ b/modules/gds/pages/featurizer.adoc @@ -72,7 +72,7 @@ Print the list of available algorithms in GDS. === installAlgorithm() -`installAlgorithm(query_name: str, query_path: str = None, global_change: bool = False) -> str` +`installAlgorithm(query_name: str, query_path: str = None, global_change: bool = False, distributed_query: bool = False) -> str` Checks if the query is already installed. If the query is not installed, it installs the query and changes the schema if an attribute needs to be added. @@ -80,11 +80,12 @@ If the query is not installed, it installs the query and changes the schema if a [discrete] ==== Parameters: * `query_name (str)`: The name of query to be installed. -* `query_path (str)`: If using a custom query, the path to the `.gsql` file that contains the query. +* `query_path (str, optional)`: If using a custom query, the path to the `.gsql` file that contains the query. Note: you must have the `query_name` parameter match the name of the query in the file. -* `global_change (bool)`: False by default. Set to true if you want to run `GLOBAL SCHEMA_CHANGE JOB`. For algorithms that are not schema free we need to specify this argument. +* `global_change (bool, optional)`: False by default. Set to true if you want to run `GLOBAL SCHEMA_CHANGE JOB`. For algorithms that are not schema free we need to specify this argument. + See https://docs.tigergraph.com/gsql-ref/current/ddl-and-loading/modifying-a-graph-schema#_global_vs_local_schema_changes.[this] for more details. +* `distributed_query (bool, optional)`: False by default. [discrete] ==== Returns: String of query name installed. @@ -106,7 +107,7 @@ Parameter dict the algorithm takes as input. === runAlgorithm() -`runAlgorithm(query_name: str, params: dict = None, runAsync: bool = False, threadLimit: int = None, memoryLimit: int = None, feat_name: str = None, feat_type: str = None, custom_query: bool = False, schema_name: list = None, global_schema: bool = False, timeout: int = 2147480, sizeLimit: int = None, templateQuery: bool = False) -> Any` +`runAlgorithm(query_name: str, params: dict = None, runAsync: bool = False, threadLimit: int = None, memoryLimit: int = None, feat_name: str = None, feat_type: str = None, custom_query: bool = False, schema_name: list = None, global_schema: bool = False, timeout: int = 2147480, sizeLimit: int = None, templateQuery: bool = False, distributed_query: bool = False) -> Any` Runs a TigerGraph Graph Data Science Algorithm. If a built-in algorithm is not installed, it will automatically install before execution. Custom algorithms will have to be installed using the `installAlgorithm()` method. @@ -141,6 +142,7 @@ See https://docs.tigergraph.com/gsql-ref/current/ddl-and-loading/modifying-a-gra See https://docs.tigergraph.com/graph-ml/current/using-an-algorithm/#_packaged_template_queries[this] for more details. for more details. Note that currently not every algorithm supports template query. More will be added in the future. Default: False. +* `distributed_query (bool, optional)`: Whether to run the query in distributed mode. Defaults to False. [discrete] ==== Returns: diff --git a/modules/gds/pages/gds.adoc b/modules/gds/pages/gds.adoc index a4af827..33e0875 100644 --- a/modules/gds/pages/gds.adoc +++ b/modules/gds/pages/gds.adoc @@ -81,7 +81,7 @@ Whether to add a topic for each epoch. Defaults to False. == neighborLoader() -`neighborLoader(v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, batch_size: int = None, num_batches: int = 1, num_neighbors: int = 10, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> NeighborLoader` +`neighborLoader(v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, v_seed_types: Union[str, list] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, batch_size: int = None, num_batches: int = 1, num_neighbors: int = 10, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> NeighborLoader` Returns a `NeighborLoader` instance. A `NeighborLoader` instance performs neighbor sampling from vertices in the graph in batches in the following manner: @@ -138,6 +138,9 @@ certain attribute doesn't exist in all vertex types. If it is a dict, keys of th dict are vertex types to be selected, and values are lists of attributes to be selected for each vertex type. Numeric, boolean and string attributes are allowed. Defaults to None. +* `v_seed_types (str or list, optional)`: Directly specify the vertex types to use as seeds. If not specified, defaults to +the vertex types used in filter_by. If not specified there, uses all vertex types. +Defaults to None. * `e_in_feats (list or dict, optional)`: Edge attributes to be used as input features. If it is a list, then the attributes in the list from all edge types will be selected. An error will be thrown if @@ -414,7 +417,7 @@ can be included as seeds. If a dictionary is provided, must be in the form of: {"vertex_type": "attribute"}. If a list, must contain multiple filters and an unique loader will be returned for each list element. Defaults to None. * `output_format (str, optional)`: Format of the output data of the loader. -Only "PyG", "DGL", "spektral", and "dataframe" are supported. Defaults to "dataframe". +Only "PyG", "DGL", "spektral", and "dataframe" are supported. Defaults to "PyG". * `add_self_loop (bool, optional)`: Whether to add self-loops to the graph. Defaults to False. * `loader_id (str, optional)`: An identifier of the loader which can be any string. It is also used as the Kafka topic name if Kafka topic is not given. If `None`, a random string will be generated @@ -435,7 +438,7 @@ for examples. == edgeNeighborLoader() -`edgeNeighborLoader(v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, batch_size: int = None, num_batches: int = 1, num_neighbors: int = 10, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> EdgeNeighborLoader` +`edgeNeighborLoader(v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, e_seed_types: Union[str, list] = None, batch_size: int = None, num_batches: int = 1, num_neighbors: int = 10, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> EdgeNeighborLoader` Returns an `EdgeNeighborLoader` instance. An `EdgeNeighborLoader` instance performs neighbor sampling from all edges in the graph in batches in the following manner: @@ -512,6 +515,9 @@ selected. An error will be thrown if certain attribute doesn't exist in all edge types. If it is a dict, keys of the dict are edge types to be selected, and values are lists of attributes to be selected for each edge type. Numeric, boolean and string attributes are allowed. Defaults to None. +* `e_seed_types (str or list, optional)`: Directly specify the edge types to use as seeds. If not specified, defaults to +the edge types used in filter_by. If not specified there, uses all edge types. +Defaults to None. * `batch_size (int, optional)`: Number of vertices as seeds in each batch. Defaults to None. * `num_batches (int, optional)`: Number of batches to split the vertices into as seeds. @@ -621,7 +627,7 @@ for examples. == hgtLoader() -`hgtLoader(num_neighbors: dict, v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, batch_size: int = None, num_batches: int = 1, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> HGTLoader` +`hgtLoader(num_neighbors: dict, v_in_feats: Union[list, dict] = None, v_out_labels: Union[list, dict] = None, v_extra_feats: Union[list, dict] = None, v_seed_types: Union[str, list] = None, e_in_feats: Union[list, dict] = None, e_out_labels: Union[list, dict] = None, e_extra_feats: Union[list, dict] = None, batch_size: int = None, num_batches: int = 1, num_hops: int = 2, shuffle: bool = False, filter_by: str = None, output_format: str = "PyG", add_self_loop: bool = False, loader_id: str = None, buffer_size: int = 4, reverse_edge: bool = False, delimiter: str = "|", timeout: int = 300000, callback_fn: Callable = None, reinstall_query: bool = False, distributed_query: bool = False) -> HGTLoader` Returns a `HGTLoader` instance. A `HGTLoader` instance performs stratified neighbor sampling from vertices in the graph in batches in the following manner: @@ -677,6 +683,9 @@ certain attribute doesn't exist in all vertex types. If it is a dict, keys of th dict are vertex types to be selected, and values are lists of attributes to be selected for each vertex type. Numeric, boolean and string attributes are allowed. Defaults to None. +* `v_seed_types (str or list, optional)`: Directly specify the vertex types to use as seeds. If not specified, defaults to +the vertex types used in filter_by. If not specified there, uses all vertex types. +Defaults to None. * `e_in_feats (list or dict, optional)`: Edge attributes to be used as input features. If it is a list, then the attributes in the list from all edge types will be selected. An error will be thrown if diff --git a/modules/intro/images/TG_Icon_Library-107.png b/modules/intro/images/TG_Icon_Library-107.png new file mode 100644 index 0000000..bc34eb3 Binary files /dev/null and b/modules/intro/images/TG_Icon_Library-107.png differ diff --git a/modules/intro/images/TG_Icon_Library-216.png b/modules/intro/images/TG_Icon_Library-216.png new file mode 100644 index 0000000..c08cbcf Binary files /dev/null and b/modules/intro/images/TG_Icon_Library-216.png differ diff --git a/modules/intro/images/TG_Icon_Library-26.png b/modules/intro/images/TG_Icon_Library-26.png new file mode 100644 index 0000000..6faaf29 Binary files /dev/null and b/modules/intro/images/TG_Icon_Library-26.png differ diff --git a/modules/intro/images/TG_Icon_Library-86.png b/modules/intro/images/TG_Icon_Library-86.png new file mode 100644 index 0000000..fa8a4da Binary files /dev/null and b/modules/intro/images/TG_Icon_Library-86.png differ diff --git a/modules/intro/images/TG_Icon_Library-90.png b/modules/intro/images/TG_Icon_Library-90.png new file mode 100644 index 0000000..f7db9e2 Binary files /dev/null and b/modules/intro/images/TG_Icon_Library-90.png differ diff --git a/modules/intro/images/datasciance_machinelearning.png b/modules/intro/images/datasciance_machinelearning.png new file mode 100644 index 0000000..bd5f8bd Binary files /dev/null and b/modules/intro/images/datasciance_machinelearning.png differ diff --git a/modules/intro/images/documentation-homecard.png b/modules/intro/images/documentation-homecard.png new file mode 100644 index 0000000..3483ec4 Binary files /dev/null and b/modules/intro/images/documentation-homecard.png differ diff --git a/modules/intro/images/getstarted-homecard.png b/modules/intro/images/getstarted-homecard.png new file mode 100644 index 0000000..cd45ceb Binary files /dev/null and b/modules/intro/images/getstarted-homecard.png differ diff --git a/modules/intro/images/lang2.png b/modules/intro/images/lang2.png new file mode 100644 index 0000000..a811ef5 Binary files /dev/null and b/modules/intro/images/lang2.png differ diff --git a/modules/intro/pages/index.adoc b/modules/intro/pages/index.adoc index 972e48c..86eadcd 100644 --- a/modules/intro/pages/index.adoc +++ b/modules/intro/pages/index.adoc @@ -2,15 +2,84 @@ :description: Overview of pyTigerGraph. pyTigerGraph is a Python package for connecting to TigerGraph databases. + +*Already familiar with pyTigerGraph?* Join the xref:_pytigergraph_community[], else, get to know pyTigerGraph below. + +== Get to Know pyTigerGraph +[.home-card,cols="2,2",grid=none,frame=none, separator=¦] +|=== +¦ +image:getstarted-homecard.png[alt=admin,width=74,height=74] +*Get Started* + +Step-by-step guides to help you get up and running. + +xref:pytigergraph:getting-started:index.adoc[Get Started |] +xref:pytigergraph:getting-started:101.adoc[pyTiger 101] + +¦ +image:datasciance_machinelearning.png[alt=admin,width=74,height=74] +*Core Functions* + +xref:pytigergraph:core-functions:index.adoc[Core Functions] +allow you to use the core features of the TigerGraph database through pyTigerGraph. + +¦ +image:TG_Icon_Library-216.png[alt=admin,width=74,height=74] +*GDS Functions* + +Graph Data Science xref:pytigergraph:gds:index.adoc[(GDS) Functions] perform machine learning tasks. + +¦ +image:TG_Icon_Library-90.png[alt=admin,width=74,height=74] +*Datasets* + +xref:pytigergraph:datasets:datasets.adoc[Data Ingestion Functions] ingest stock datasets into a TigerGraph database. + +¦ +image:TG_Icon_Library-86.png[alt=admin,width=74,height=74] +*Visualizations* + +Use xref:visualization:visualization.adoc[Visualizations] to visualize graphs. + +¦ +image:TG_Icon_Library-26.png[alt=admin,width=74,height=74] +*Object-Oriented Schema* + +The xref:object_oriented_schema:schema-def.adoc[Object-Oriented Schema] functionality allows users to manipulate schema elements in the database in an object-oriented approach in Python. + +¦ +image:TG_Icon_Library-107.png[alt=admin,width=74,height=74] +*Contribute* + +Checkout the xref:pytigergraph:contributing:index.adoc[Contributing] section for instructions on how to contribute. + +¦ +image:documentation-homecard.png[alt=admin,width=74,height=74] +*Release Notes* + +See xref:pytigergraph:release-notes:index.adoc[Release Notes] +for the most up-to-date news on pyTigerGraph. + +|=== + +== pyTigerGraph Community +There are many community resources that you can use for help and support using pyTigerGraph: + +* https://dev.tigergraph.com/forum/[TigerGraph Community Forum] +* https://discord.gg/XM7Cn9w[TigerGraph Community Discord] +* https://github.com/tigergraph/pyTigerGraph/issues[pyTigerGraph GitHub Issues] + +== pyTigerGraph vs. pyTigerGraph[gds] We offer two versions of the package: _pyTigerGraph_ and _pyTigerGraph[gds]_. _pyTigerGraph_ is the default version and contains the core functionality of pyTigerGraph, including the following: * Data manipulation functions:inserting, updating, upserting, deleting, and retrieving vertices and edges. * Query functions: running and managing xref:gsql-ref:querying:query-operations.adoc[queries] inside the TigerGraph - database +database * Metadata functions: fetching details of graphs/schemas, vertex and edge types, and other - schema objects and object types +schema objects and object types * Authentication and authorization functions * Miscellaneous utility functions @@ -21,24 +90,3 @@ This includes: * Graph feature engineering using algorithms from the xref:graph-ml:intro:[GSQL Graph Data Science Library]. * Data loaders for training and inference of Graph Neural Network (GNN) models using PyTorch Geometric and DGL. * Machine learning utilities for splitting vertices into training, validation, and testing sets. - -== Getting Started -Checkout the xref:getting-started:index.adoc[Getting Started] section for a quick introduction to pyTigerGraph. -It walks you through how to perform the following: - -* xref:getting-started:install.adoc[] -* xref:getting-started:connection.adoc[] - -In addition, we also provide a video tutorial and a Google Colab notebook that walks you through all core functions of pyTigergraph: - -* xref:getting-started:101.adoc[] - -== pyTigerGraph Community -There are many community resources that you can use for help and support using pyTigerGraph: - -* https://dev.tigergraph.com/forum/[TigerGraph Community Forum] -* https://discord.gg/XM7Cn9w[TigerGraph Community Discord] -* https://github.com/tigergraph/pyTigerGraph/issues[pyTigerGraph GitHub Issues] - -== Contributing -Checkout the xref:contributing:index.adoc[Contributing] section for instructions on how to contribute. pyTigerGraph was started as an open-source community project, and we welcome contributions from the community. \ No newline at end of file diff --git a/modules/object_oriented_schema/nav.adoc b/modules/object_oriented_schema/nav.adoc new file mode 100644 index 0000000..0b38018 --- /dev/null +++ b/modules/object_oriented_schema/nav.adoc @@ -0,0 +1 @@ +* xref:schema-def.adoc[Object Oriented Schema] \ No newline at end of file diff --git a/modules/object_oriented_schema/pages/schema-def.adoc b/modules/object_oriented_schema/pages/schema-def.adoc new file mode 100644 index 0000000..4d00f2c --- /dev/null +++ b/modules/object_oriented_schema/pages/schema-def.adoc @@ -0,0 +1,275 @@ += Object-Oriented Schema + +The Object-Oriented Schema functionality allows users to manipulate schema elements in the database in an object-oriented approach in Python. + +To add an AccountHolder vertex and a HOLDS_ACCOUNT edge to the Ethereum dataset, simply: + +``` +from pyTigerGraph import TigerGraphConnection +from pyTigerGraph.schema import Graph, Vertex, Edge + +from datetime import datetime +from typing import List, Dict, Optional, Union +from dataclasses import dataclass, fields + +conn = TigerGraphConnection(host="http://YOUR_HOSTNAME_HERE", graphname="Ethereum") + +g = Graph(conn) + + +@dataclass +class AccountHolder(Vertex): + name: str + address: str + accounts: List[str] + dob: datetime + some_map: Dict[str, int] + some_double: "DOUBLE" + primary_id: str = "name" # always of type string, corresponds to the desired primary ID attribute. + primary_id_as_attribute: bool = True + +@dataclass +class HOLDS_ACCOUNT(Edge): + opened_on: datetime + from_vertex: Union[AccountHolder, g.vertex_types["Account"]] + to_vertex: g.vertex_types["Account"] + is_directed: bool = True + reverse_edge: str = "ACCOUNT_HELD_BY" + discriminator: str = "opened_on" + +g.add_vertex_type(AccountHolder) + +g.add_edge_type(HOLDS_ACCOUNT) + +g.commit_changes() +``` + +Users can define an entire graph schema in the approach below. Using the Cora dataset example, the schema would look something like this: + +``` +from pyTigerGraph import TigerGraphConnection +from pyTigerGraph.schema import Graph, Vertex, Edge + +conn = TigerGraphConnection("http://YOUR_HOSTNAME_HERE") + +g = Graph() + +@dataclass +class Paper(Vertex): + id: int + y: int + x: List[int] + primary_id: str = "id" + primary_id_as_attribute: bool = True + +@dataclass +class CITES(Edge): + from_vertex: Paper + to_vertex: Paper + is_directed: bool = True + reverse_edge: str = "R_CITES" + +g.add_vertex_type(Paper) +g.add_edge_type(CITES) + +g.commit_changes(conn) +``` + +== Vertex + +Abstract parent class for other types of vertices to be inherited from. +Contains class methods to edit the attributes associated with the vertex type. + +When defining new vertex types, make sure to include the `primary_id` and `primary_id_as_attribute` class attributes, as these are necessary to define the vertex in TigerGraph. + +For example, to define an AccountHolder vertex type, use: + + +[source,indent=0] +---- +@dataclass +class AccountHolder(Vertex): + name: str + address: str + accounts: List[str] + dob: datetime + some_map: Dict[str, int] + some_double: "DOUBLE" + primary_id: str = "name" + primary_id_as_attribute: bool = True +---- + + + +=== add_attribute() +`add_attribute(attribute_name: str, attribute_type, default_value = None)` + +Function to add an attribute to the given vertex type. + +[discrete] +==== Parameters: +* `attribute_name (str)`: The name of the attribute to add +* `attribute_type (Python type)`: The Python type of the attribute to add. +For types that are not supported in Python but are in GSQL, wrap them in quotes; e.g. "DOUBLE" +* `default_value (type of attribute, default None)`: The desired default value of the attribute. Defaults to None. + + +=== remove_attribute() +`remove_attribute(attribute_name)` + +Function to remove an attribute from the given vertex type. + +[discrete] +==== Parameter: +* `attribute_name (str)`: The name of the attribute to remove from the vertex. + + +=== attributes() +`attributes()` + +Class attribute to view the attributes and types of the vertex. + + +== Edge + +Abstract parent class for other types of edges to be inherited from. +Contains class methods to edit the attributes associated with the edge type. + +When defining new vertex types, make sure to include the required `from_vertex`, `to_vertex`, `reverse_edge`, `is_directed` attributes and optionally the `discriminator` attribute, as these are necessary to define the vertex in TigerGraph. + +For example, to define an HOLDS_ACCOUNT edge type, use: + + +[source,indent=0] +---- +@dataclass +class HOLDS_ACCOUNT(Edge): + opened_on: datetime + from_vertex: Union[AccountHolder, g.vertex_types["Account"]] + to_vertex: g.vertex_types["Account"] + is_directed: bool = True + reverse_edge: str = "ACCOUNT_HELD_BY" + discriminator: str = "opened_on" +---- + + + +=== add_attribute() +`add_attribute(attribute_name, attribute_type, default_value = None)` + +Function to add an attribute to the given edge type. + +[discrete] +==== Parameters: +* `attribute_name (str)`: The name of the attribute to add. +* `attribute_type (Python type)`: The Python type of the attribute to add. +For types that are not supported in Python but are in GSQL, wrap them in quotes; e.g. "DOUBLE" +* `default_value (type of attribute, default None)`: The desired default value of the attribute. Defaults to None. + + +=== remove_attribute() +`remove_attribute(attribute_name)` + +Function to remove an attribute from the given edge type. + +[discrete] +==== Parameter: +* `attribute_name (str)`: The name of the attribute to remove from the edge. + + +=== attributes() +`attributes()` + +Class attribute to view the attributes and types of the vertex. + + +== Graph + +The graph object can be used in conjunction with a TigerGraphConnection to retrieve the schema of the connected graph. +Serves as the way to collect the definitions of Vertex and Edge types. + +To instantiate the graph object with a connection to an existing graph, use: + +[source,indent=0] +---- +from pyTigerGraph.schema import Graph + +g = Graph(conn) +---- + + + +=== \__init__() +`__init__(conn: TigerGraphConnection = None)` + +Graph class for schema representation. + +[discrete] +==== Parameter: +* `conn (TigerGraphConnection, optional)`: Connection to a TigerGraph database. Defaults to None. + + +=== add_vertex_type() +`add_vertex_type(vertex: Vertex, outdegree_stats = True)` + +Add a vertex type to the list of changes to commit to the graph. + +[discrete] +==== Parameters: +* `vertex (Vertex)`: The vertex type definition to add to the addition cache. +* `outdegree_stats (bool, optional)`: Whether or not to include "WITH OUTEGREE_STATS=TRUE" in the schema definition. +Used for caching outdegree, defaults to True. + + +=== add_edge_type() +`add_edge_type(edge: Edge)` + +Add an edge type to the list of changes to commit to the graph. + +[discrete] +==== Parameter: +* `edge (Edge)`: The edge type definition to add to the addition cache. + + +=== remove_vertex_type() +`remove_vertex_type(vertex: Vertex)` + +Add a vertex type to the list of changes to remove from the graph. + +[discrete] +==== Parameter: +* `vertex (Vertex)`: The vertex type definition to add to the removal cache. + + +=== remove_edge_type() +`remove_edge_type(edge: Edge)` + +Add an edge type to the list of changes to remove from the graph. + +[discrete] +==== Parameter: +* `edge (Edge)`: The edge type definition to add to the removal cache. + + +=== commit_changes() +`commit_changes(conn: TigerGraphConnection = None)` + +Commit schema changes to the graph. +[discrete] +==== Parameter: +* `conn (TigerGraphConnection, optional)`: Connection to the database to edit the schema of. +Not required if the Graph was instantiated with a connection object. + + +=== vertex_types() +`vertex_types()` + +Vertex types property. + + +=== edge_types() +`edge_types()` + +Edge types property. + + diff --git a/modules/release-notes/nav.adoc b/modules/release-notes/nav.adoc index b71ee0a..138b230 100644 --- a/modules/release-notes/nav.adoc +++ b/modules/release-notes/nav.adoc @@ -1 +1,2 @@ -* xref:index.adoc[Release Notes] \ No newline at end of file +* xref:index.adoc[Release Notes] +** xref:legacy-tg-versions.adoc[] \ No newline at end of file diff --git a/modules/release-notes/pages/index.adoc b/modules/release-notes/pages/index.adoc index 0512c67..f0fc0a4 100644 --- a/modules/release-notes/pages/index.adoc +++ b/modules/release-notes/pages/index.adoc @@ -1,5 +1,18 @@ = Release Notes +== [1.5] - 2023-09-25 + +Release of pyTigerGraph version 1.5. + +=== Added: +* xref:pytigergraph:object_oriented_schema:schema-def.adoc[Object-oriented schema definition and modifcation]. Define graph schemas in native Python, without knowing GSQL. +* `gsql()` handles some common error cases and raises an exception if they occur. + +=== Changed: +* Dataloaders that experience a parsing error due to missing/dirty data handle the error more gracefully. +* Removed the use of pyTigerDriver for GSQL operations. +* Various bug fixes. + == [1.4] - 2023-05-16 Release of pyTigerGraph version 1.4. diff --git a/modules/release-notes/pages/legacy-tg-versions.adoc b/modules/release-notes/pages/legacy-tg-versions.adoc new file mode 100644 index 0000000..ab2a91a --- /dev/null +++ b/modules/release-notes/pages/legacy-tg-versions.adoc @@ -0,0 +1,11 @@ += Legacy Version Documentation + +This page lists the previous versions of pyTigerGraph. + +* 1.4 +* 1.3 +* 1.2 +* 1.1 +* 1.0 + +https://github.com/tigergraph/pyTigerGraph/tags