GFQL User-Defined Function (UDF) Endpoints
This is a Graphistry server HTTP endpoint for creating and executing user defined GFQL endpoints, which execute pre-defined GFQL actions on datasets either retrieved or generated on execution, or predefined on UDF creation. See GFQL documentation more in-depth information on the use of GFQL in general.
Access to this feature is controlled through a flag_create_gfql_udf feature flag which disables or enables GFQL type named endpoint creation only. Each individual named endpoint can be enabled and disabled independently as well. The requisite GFQL feature flag flag_gfql_endpoint must also be enabled to enable execution of GFQL defined endpoints.
List UDFs
Endpoint
GET /api/v2/o/<org_slug>/functions/gfql/
This endpoint lists all UDF endpoints created under the provided organization which the currently authenticated user has edit access to.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.
Query Parameters:
limit(optional): Integer limiting the number of UDF endpoint results in one page for pagination.offset(required): Integer specifying the page to view assuming pagination is necessary.
Response (JSON):
| Parameter | Type | Description |
|---|---|---|
| count | int |
Integer containing the number of UDF endpoints created under this organization. |
| next | string, null |
String containing a link to the next page of results if it exists, assuming pagination is necessary. |
| previous | string, null |
String containing a link to the previous page of results if it exists, assuming pagination is necessary. |
| results | Object[] |
Array of objects where each object contains the specification for a UDF endpoint. The definition for each object in the array is identical to that returned when an individual UDF definition is returned using a GET request. |
Get UDF Definition
Endpoint
GET /api/v2/o/<org_slug>/functions/gfql/<udf_uuid_or_alias>
This endpoint returns a specific UDF endpoint created under the provided organization.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>In addition, the user making the request must be given editor permissions by the owner of the endpoint in question.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(required): String containing the identifier for the UDF endpoint defined at creation.
Query Parameters:
limit(optional): Integer limiting the number of UDF endpoint results in one page for pagination.offset(required): Integer specifying the page to view assuming pagination is necessary.
Response (JSON):
| Parameter | Type | Description |
|---|---|---|
| alias | string, null |
String with a user settable ID which can be used as an ID for this endpoint. The alias must be unique among all endpoints under the organization. |
| author | string |
String containing the user ID of the creator of this endpoint. |
| is_enabled | boolean |
Boolean controlling whether the UDF can be executed or not. |
| organization | string |
String containing the organization ID of the owner of the UDF endpoint. |
| type | string |
String representing the type of UDF endpoint this represents. |
| created_at | string |
String holding a datetime string following ISO 8601 standard of the time this endpoint was created. |
| updated_at | string |
String holding a datetime string following ISO 8601 standard of the last time this endpoint definition was updated. |
| uuid | string |
String containing the unique ID of this endpoint which can be used to execute it. |
| load_dataset | string |
String containing the Graphistry dataset ID of the graph to run GFQL on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL. |
| output_type | all, nodes, edges, shape |
String which changes output contents. Specify nodes or edges respectively for the corresponding property table. Specify shape for the node and edge table row/column counts without returning the actual result tables. Leave blank or specify all to return the full graph, meaning both the node and edge tables. If the output format is json, then an array containing only a node table or edge table is returned rather than an object containing both. If the output format is of a type returning binary files, then all triggers returning a zip file of the corresponding format files. |
| gfql_operations | string |
Array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation. Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed. If left empty the entire graph is retrieved, which can be used to download datasets. |
| format | string |
String which specifies the format used to encode returned graph data. Valid strings include json, csv, or parquet. If both nodes or edges are requested, the data is returned inside a zip file containing a nodes and an edges file, otherwise the raw text or binary is returned. |
| node_col_subset | string[] |
Array of strings which specifies the subset of node properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| edge_col_subset | string[] |
Array of strings which specifies the subset of edge properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| df_export_args | Object |
Object containing arguments to be passed to the function serializing the result dataframe. The specific arguments permitted vary depending on the format of data requested. If the format requested is json, then valid arguments include engine, orient, date_format, double_precision, force_ascii, date_unit, and index. If the format requested is csv, then valid arguments include sep, na_rep, header, index, and encoding. If the format requested is parquet, then valid arguments include compression, and index. See linked documents for more information on arguments passed. |
| engine | cudf, pandas |
Whether to load the graph and query it in the GPU (cudf) or CPU (pandas). When unspecified, graph is inspected to determine where to run it, such as by examining file size. |
Create UDF Definition
Endpoint
POST /api/v2/o/<org_slug>/functions/gfql/<udf_uuid_or_alias>
This endpoint accepts requests to create a new UDF endpoint.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>The user creating the endpoint must have the flag_create_gfql_udf Waffle flag enabled.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(optional): String containing the identifier for the UDF endpoint defined at creation. If omitted a unique UUID will be assigned.
Body Parameters (JSON):
| Parameter | Type | Default | Description |
|---|---|---|---|
| is_enabled | boolean |
false | Boolean controlling whether the UDF can be executed or not. |
| load_dataset | string |
- | String containing the Graphistry dataset ID of the graph to run GFQL on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL. |
| output_type | all, nodes, edges, shape |
- | String which changes output contents. Specify nodes or edges respectively for the corresponding property table. Specify shape for the node and edge table row/column counts without returning the actual result tables. Leave blank or specify all to return the full graph, meaning both the node and edge tables. If the output format is json, then an array containing only a node table or edge table is returned rather than an object containing both. If the output format is of a type returning binary files, then all triggers returning a zip file of the corresponding format files. |
| gfql_operations | string |
- | Array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation. Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed. If left empty the entire graph is retrieved, which can be used to download datasets. |
| format | string |
json | String which specifies the format used to encode returned graph data. Valid strings include json, csv, or parquet. If both nodes or edges are requested, the data is returned inside a zip file containing a nodes and an edges file, otherwise the raw text or binary is returned. |
| node_col_subset | string[] |
- |
Array of strings which specifies the subset of node properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| edge_col_subset | string[] |
- |
Array of strings which specifies the subset of edge properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| df_export_args | Object |
- |
Object containing arguments to be passed to the function serializing the result dataframe. The specific arguments permitted vary depending on the format of data requested. If the format requested is json, then valid arguments include engine, orient, date_format, double_precision, force_ascii, date_unit, and index. If the format requested is csv, then valid arguments include sep, na_rep, header, index, and encoding. If the format requested is parquet, then valid arguments include compression, and index. See linked documents for more information on arguments passed. |
| engine | cudf, pandas |
Infer | Whether to load the graph and query it in the GPU (cudf) or CPU (pandas). When unspecified, graph is inspected to determine where to run it, such as by examining file size. |
Response (JSON):
| Parameter | Type | Description |
|---|---|---|
| alias | string |
String with a user settable ID which can be used as an ID for this endpoint. The alias must be unique among all endpoints under the organization. |
| author | string |
String containing the user ID of the creator of this endpoint. |
| is_enabled | boolean |
Boolean controlling whether the UDF can be executed or not. |
| organization | string |
String containing the organization ID of the owner of the UDF endpoint. |
| type | string |
String representing the type of UDF endpoint this represents. |
| created_at | string |
String holding a datetime string following ISO 8601 standard of the time this endpoint was created. |
| updated_at | string |
String holding a datetime string following ISO 8601 standard of the last time this endpoint definition was updated. |
| uuid | string |
String containing the unique ID of this endpoint which can be used to execute it. |
| load_dataset | string |
String containing the Graphistry dataset ID of the graph to run GFQL on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL. |
| output_type | all, nodes, edges, shape |
String which changes output contents. Specify nodes or edges respectively for the corresponding property table. Specify shape for the node and edge table row/column counts without returning the actual result tables. Leave blank or specify all to return the full graph, meaning both the node and edge tables. If the output format is json, then an array containing only a node table or edge table is returned rather than an object containing both. If the output format is of a type returning binary files, then all triggers returning a zip file of the corresponding format files. |
| gfql_operations | string |
Array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation. Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed. If left empty the entire graph is retrieved, which can be used to download datasets. |
| format | string |
String which specifies the format used to encode returned graph data. Valid strings include json, csv, or parquet. If both nodes or edges are requested, the data is returned inside a zip file containing a nodes and an edges file, otherwise the raw text or binary is returned. |
| node_col_subset | string[] |
Array of strings which specifies the subset of node properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| edge_col_subset | string[] |
Array of strings which specifies the subset of edge properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| df_export_args | Object |
Object containing arguments to be passed to the function serializing the result dataframe. The specific arguments permitted vary depending on the format of data requested. If the format requested is json, then valid arguments include engine, orient, date_format, double_precision, force_ascii, date_unit, and index. If the format requested is csv, then valid arguments include sep, na_rep, header, index, and encoding. If the format requested is parquet, then valid arguments include compression, and index. See linked documents for more information on arguments passed. |
| engine | cudf, pandas |
Whether to load the graph and query it in the GPU (cudf) or CPU (pandas). When unspecified, graph is inspected to determine where to run it, such as by examining file size. |
Update UDF Definition
Endpoint
PUT /api/v2/o/<org_slug>/functions/gfql/<udf_uuid_or_alias>
This endpoint accepts requests to update an existing UDF endpoint.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>In addition, the user making the request must be given editor permissions by the owner of the endpoint in question.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(required): String containing the identifier for the UDF endpoint defined at creation.
Body Parameters (JSON):
All parameters are optional. Only parameters which are to be updated need to be included in the body. All omitted parameters are assumed to be unchanged.
| Parameter | Type | Default | Description |
|---|---|---|---|
| is_enabled | boolean |
false | Boolean controlling whether the UDF can be executed or not. |
| load_dataset | string |
- | String containing the Graphistry dataset ID of the graph to run GFQL on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL. |
| output_type | all, nodes, edges, shape |
- | String which changes output contents. Specify nodes or edges respectively for the corresponding property table. Specify shape for the node and edge table row/column counts without returning the actual result tables. Leave blank or specify all to return the full graph, meaning both the node and edge tables. If the output format is json, then an array containing only a node table or edge table is returned rather than an object containing both. If the output format is of a type returning binary files, then all triggers returning a zip file of the corresponding format files. |
| gfql_operations | string |
- | Array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation. Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed. If left empty the entire graph is retrieved, which can be used to download datasets. |
| format | string |
json | String which specifies the format used to encode returned graph data. Valid strings include json, csv, or parquet. If both nodes or edges are requested, the data is returned inside a zip file containing a nodes and an edges file, otherwise the raw text or binary is returned. |
| node_col_subset | string[] |
- |
Array of strings which specifies the subset of node properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| edge_col_subset | string[] |
- |
Array of strings which specifies the subset of edge properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| df_export_args | Object |
- |
Object containing arguments to be passed to the function serializing the result dataframe. The specific arguments permitted vary depending on the format of data requested. If the format requested is json, then valid arguments include engine, orient, date_format, double_precision, force_ascii, date_unit, and index. If the format requested is csv, then valid arguments include sep, na_rep, header, index, and encoding. If the format requested is parquet, then valid arguments include compression, and index. See linked documents for more information on arguments passed. |
| engine | cudf, pandas |
Infer | Whether to load the graph and query it in the GPU (cudf) or CPU (pandas). When unspecified, graph is inspected to determine where to run it, such as by examining file size. |
Response (JSON):
| Parameter | Type | Description |
|---|---|---|
| alias | string |
String with a user settable ID which can be used as an ID for this endpoint. The alias must be unique among all endpoints under the organization. |
| author | string |
String containing the user ID of the creator of this endpoint. |
| is_enabled | boolean |
Boolean controlling whether the UDF can be executed or not. |
| organization | string |
String containing the organization ID of the owner of the UDF endpoint. |
| type | string |
String representing the type of UDF endpoint this represents. |
| created_at | string |
String holding a datetime string following ISO 8601 standard of the time this endpoint was created. |
| updated_at | string |
String holding a datetime string following ISO 8601 standard of the last time this endpoint definition was updated. |
| uuid | string |
String containing the unique ID of this endpoint which can be used to execute it. |
| load_dataset | string |
String containing the Graphistry dataset ID of the graph to run GFQL on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL. |
| output_type | all, nodes, edges, shape |
String which changes output contents. Specify nodes or edges respectively for the corresponding property table. Specify shape for the node and edge table row/column counts without returning the actual result tables. Leave blank or specify all to return the full graph, meaning both the node and edge tables. If the output format is json, then an array containing only a node table or edge table is returned rather than an object containing both. If the output format is of a type returning binary files, then all triggers returning a zip file of the corresponding format files. |
| gfql_operations | string |
Array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation. Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed. If left empty the entire graph is retrieved, which can be used to download datasets. |
| format | string |
String which specifies the format used to encode returned graph data. Valid strings include json, csv, or parquet. If both nodes or edges are requested, the data is returned inside a zip file containing a nodes and an edges file, otherwise the raw text or binary is returned. |
| node_col_subset | string[] |
Array of strings which specifies the subset of node properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| edge_col_subset | string[] |
Array of strings which specifies the subset of edge properties to be returned as results, using the property names as identifiers. This array can also be used to change the order the properties are stored in the returned data. |
| df_export_args | Object |
Object containing arguments to be passed to the function serializing the result dataframe. The specific arguments permitted vary depending on the format of data requested. If the format requested is json, then valid arguments include engine, orient, date_format, double_precision, force_ascii, date_unit, and index. If the format requested is csv, then valid arguments include sep, na_rep, header, index, and encoding. If the format requested is parquet, then valid arguments include compression, and index. See linked documents for more information on arguments passed. |
| engine | cudf, pandas |
Whether to load the graph and query it in the GPU (cudf) or CPU (pandas). When unspecified, graph is inspected to determine where to run it, such as by examining file size. |
Delete UDF Definition
Endpoint
DELETE /api/v2/o/<org_slug>/functions/gfql/<udf_uuid_or_alias>
This endpoint deletes a defined UDF endpoint.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>In addition, the user making the request must be given editor permissions by the owner of the endpoint in question.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(required): String containing the identifier for the UDF endpoint defined at creation.
Run UDF Definition using pre-defined dataset
Endpoint
POST /api/v2/o/<org_slug>/run/gfql/<udf_uuid_or_alias>
This endpoint runs a pre-defined UDF endpoint using either load_dataset or load_data methods to retrieve a graph to use as input.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>In addition, the user making the request must be given run permissions by the owner of the endpoint in question.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(required): String containing the identifier for the UDF endpoint defined at creation.
Run UDF Definition using URL provided dataset
Endpoint
POST /api/v2/o/<org_slug>/run/gfql/<udf_uuid_or_alias>/dataset/<dataset_id>
This endpoint runs a pre-defined UDF endpoint using a dataset ID provided in the URL to retrieve a graph to use as input. By consequence, both load_dataset and load_data methods defined in the UDF are ignored.
Authentication
Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header, or are authenticated by a CSRF token included with the cookies sent with a request.
Authorization: Bearer <your_jwt_token>In addition, the user making the request must be given run permissions by the owner of the endpoint in question.
Request Parameters
URL Parameters:
org_slug(required): String containing the org identifier of the creator of the UDF endpoint.udf_uuid_or_alias(required): String containing the identifier for the UDF endpoint defined at creation.dataset_id(required): String containing a unique identifier of the dataset to query.
Notes
- Ensure the JWT token used for authentication has sufficient permissions to access the dataset.
- The
gfql_operationsparameter allows for significant flexibility in query construction; refer to the GFQL specification for detailed usage.