V1.5

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

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",

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`.

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:

modules/gds/pages/featurizer.adoc

@@ -72,19 +72,20 @@ 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.
 
 [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:

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

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.

modules/object_oriented_schema/nav.adoc

@@ -0,0 +1 @@
+* xref:schema-def.adoc[Object Oriented Schema]