UI Guides

Graphistry Setup

REST APIs

Introduction

2.0 REST API Tutorial (cURL)

URL API to Embed & Control

- HTML

- URL Options

- IFrame CSS Style Tips

Authentication (2.0 API)

- Concepts

- Create token

- Refresh token

- Verify token

- Modes: Password, Personal Key, & SSO

Computation

- GFQL Query Endpoint

    - GFQL Operations

    - GFQL Predicates

- Python Query Endpoint

- GFQL UDF Endpoint

- Python UDF Endpoint

Upload Data (2.0 API)

- Concepts

- List Files

- Create File

- Delete File

- Upload File Data

- List Visualization Datasets

- Create Visualization Dataset with Bindings

    - Hypergraphs

- Delete Visualization

- Schema

Basic Bindings

    - Color

    - Color Palettes

    - Edge Weight Bindings

Complex Bindings

    - Colors and Sizes

    - Icons

    - Badges

    - Radial & Horizontal Axis

    - Field Controls Overview

        - Field Inclusion

        - Field Exclusion

        - Computed Fields

- Branding Metadata: Logos, title, backgrounds, & effects

- Upload Node & Edge Data

   - json

   - csv

   - parquet

   - orc

   - arrow

Live Sessions (experimental)

- View

Health Checks

Python Notebooks & API

- PyGraphistry Homepage (GitHub)

- PyGraphistry API (ReadTheDocs)

- Jupyter Notebook Examples (GitHub)

- Pygraphistry Databricks Examples (GitHub)

- Graph Algorithms

Visual Playbooks

- Connectors

- Pivots

- Templates

JavaScript Libraries

- React - Storybook

- React - API

- Browser JS - Storybook

- Browser JS - Example

- Browser JS - API

- Node.js - API

Python User-Defined Function (UDF) Endpoints

This is a Graphistry server HTTP endpoint for creating and executing user defined Python endpoints, which execute pre-defined arbitrary Python code on datasets either retrieved or generated on execution, or predefined on UDF creation. See Python endpoint documentation more in-depth information on the use of the Python endpoint in general.

Access to this feature is controlled through a flag_create_pe_udf feature flag which disables or enables Python endpoint type named endpoint creation only. Each individual named endpoint can be enabled and disabled independently as well. The Python endpoint feature flags flag_python_endpoint_disabled must be disabled and flag_python_endpoint_enabled_users enabled to enable execution of Python user defined endpoints.

List UDFs

Endpoint

GET /api/v2/o/<org_slug>/functions/python/

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/python/<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 Python endpoint on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL.
load_data string String containing valid Python code which can be executed server-side and returns a Graphistry Plottable. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed an array of arguments. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message. This method is ignored if either load_dataset is defined, or if a dataset ID is provided in the UDF run URL.
execute string String containing valid Python code which can be executed server-side. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed the Graphistry plottable object containing the dataset specified previously. The endpoint expects that this function will return either a Python str or a JSON serializable dict which will be returned to the user. There are currently no restrictions on the code which can be run using the Python endpoint. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message.
engine cudf, pandas Whether to load the graph and query it in the GPU (cudf) or CPU (pandas).
output_type all, json, edges, nodes, table, shape What to return, using the data representation specified in accompanying parameter format
If the Python code returns a Plottable, return all or part of the graph:
  • "all": A zip file with files for the nodes and edges
  • "json": A JSON object with the nodes and edges
  • "edges": The edges table
  • "nodes": The nodes table
  • "shape": The row, column counts of the node and edge tables
When the Python is expected to return a dataframe-like (e.g., pandas.DataFrame, cudf.DataFrame, or arrow.Table):
  • "table": The table
  • "shape": The row, column counts of the table
For arbitrary returns, use "json".
format json, csv, parquet What representation to represent the returned data.

Create UDF Definition

Endpoint

POST /api/v2/o/<org_slug>/functions/python/<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 Python endpoint on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL.
load_data string - String containing valid Python code which can be executed server-side and returns a Graphistry Plottable. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed an array of arguments. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message. This method is ignored if either load_dataset is defined, or if a dataset ID is provided in the UDF run URL.
execute string - String containing valid Python code which can be executed server-side. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed the Graphistry plottable object containing the dataset specified previously. The endpoint expects that this function will return either a Python str or a JSON serializable dict which will be returned to the user. There are currently no restrictions on the code which can be run using the Python endpoint. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message.
engine cudf, pandas cudf Whether to load the graph and query it in the GPU (cudf) or CPU (pandas).
output_type all, json, edges, nodes, table, shape json What to return, using the data representation specified in accompanying parameter format
If the Python code returns a Plottable, return all or part of the graph:
  • "all": A zip file with files for the nodes and edges
  • "json": A JSON object with the nodes and edges
  • "edges": The edges table
  • "nodes": The nodes table
  • "shape": The row, column counts of the node and edge tables
When the Python is expected to return a dataframe-like (e.g., pandas.DataFrame, cudf.DataFrame, or arrow.Table):
  • "table": The table
  • "shape": The row, column counts of the table
For arbitrary returns, use "json".
format json, csv, parquet json What representation to represent the returned data.

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 Python endpoint on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL.
load_data string String containing valid Python code which can be executed server-side and returns a Graphistry Plottable. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed an array of arguments. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message. This method is ignored if either load_dataset is defined, or if a dataset ID is provided in the UDF run URL.
execute string String containing valid Python code which can be executed server-side. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed the Graphistry plottable object containing the dataset specified previously. The endpoint expects that this function will return either a Python str or a JSON serializable dict which will be returned to the user. There are currently no restrictions on the code which can be run using the Python endpoint. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message.
engine cudf, pandas Whether to load the graph and query it in the GPU (cudf) or CPU (pandas).
output_type all, json, edges, nodes, table, shape What to return, using the data representation specified in accompanying parameter format
If the Python code returns a Plottable, return all or part of the graph:
  • "all": A zip file with files for the nodes and edges
  • "json": A JSON object with the nodes and edges
  • "edges": The edges table
  • "nodes": The nodes table
  • "shape": The row, column counts of the node and edge tables
When the Python is expected to return a dataframe-like (e.g., pandas.DataFrame, cudf.DataFrame, or arrow.Table):
  • "table": The table
  • "shape": The row, column counts of the table
For arbitrary returns, use "json".
format json, csv, parquet What representation to represent the returned data.

Update UDF Definition

Endpoint

PUT /api/v2/o/<org_slug>/functions/python/<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 Python endpoint on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL.
load_data string - String containing valid Python code which can be executed server-side and returns a Graphistry Plottable. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed an array of arguments. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message. This method is ignored if either load_dataset is defined, or if a dataset ID is provided in the UDF run URL.
execute string - String containing valid Python code which can be executed server-side. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed the Graphistry plottable object containing the dataset specified previously. The endpoint expects that this function will return either a Python str or a JSON serializable dict which will be returned to the user. There are currently no restrictions on the code which can be run using the Python endpoint. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message.
engine cudf, pandas cudf Whether to load the graph and query it in the GPU (cudf) or CPU (pandas).
output_type all, json, edges, nodes, table, shape json What to return, using the data representation specified in accompanying parameter format
If the Python code returns a Plottable, return all or part of the graph:
  • "all": A zip file with files for the nodes and edges
  • "json": A JSON object with the nodes and edges
  • "edges": The edges table
  • "nodes": The nodes table
  • "shape": The row, column counts of the node and edge tables
When the Python is expected to return a dataframe-like (e.g., pandas.DataFrame, cudf.DataFrame, or arrow.Table):
  • "table": The table
  • "shape": The row, column counts of the table
For arbitrary returns, use "json".
format json, csv, parquet json What representation to represent the returned data.

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 Python endpoint on. This input graph overrides load_data and is overridden by any Graphistry dataset ID provided in the execute URL.
load_data string String containing valid Python code which can be executed server-side and returns a Graphistry Plottable. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed an array of arguments. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message. This method is ignored if either load_dataset is defined, or if a dataset ID is provided in the UDF run URL.
execute string String containing valid Python code which can be executed server-side. The endpoint expects that the Python code string will contain a function task which will be executed. This function is required to accept a single argument, which will be passed the Graphistry plottable object containing the dataset specified previously. The endpoint expects that this function will return either a Python str or a JSON serializable dict which will be returned to the user. There are currently no restrictions on the code which can be run using the Python endpoint. Import statements can be used to import all standard Python libraries in addition to a handful of other libraries, including but not limited to graphistry, cudf, numpy, and pandas. Warning: there are currently no safeguards around the endpoint such as timeouts and multithreading, bad execute requests may require the container to be restarted. Any uncaught errors in the executed code will be returned via a JSON error message.
engine cudf, pandas Whether to load the graph and query it in the GPU (cudf) or CPU (pandas).
output_type all, json, edges, nodes, table, shape What to return, using the data representation specified in accompanying parameter format
If the Python code returns a Plottable, return all or part of the graph:
  • "all": A zip file with files for the nodes and edges
  • "json": A JSON object with the nodes and edges
  • "edges": The edges table
  • "nodes": The nodes table
  • "shape": The row, column counts of the node and edge tables
When the Python is expected to return a dataframe-like (e.g., pandas.DataFrame, cudf.DataFrame, or arrow.Table):
  • "table": The table
  • "shape": The row, column counts of the table
For arbitrary returns, use "json".
format json, csv, parquet What representation to represent the returned data.

Delete UDF Definition

Endpoint

DELETE /api/v2/o/<org_slug>/functions/python/<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/python/<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.

Body Parameters (JSON):

All parameters are optional.

Parameter Type Default Description
load_data_args Object - An object containing arbitrary key-value pairs to be passed to the task function defined in the execute string as arguments. Types of keys and values are entirely dependant on the load_data definition.
execute_args Object - An object containing arbitrary key-value pairs to be passed to the task function defined in the execute string as arguments. Types of keys and values are entirely dependant on the execute definition.

Run UDF Definition using URL provided dataset

Endpoint

POST /api/v2/o/<org_slug>/run/python/<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.

Body Parameters (JSON):

All parameters are optional.

Parameter Type Default Description
load_data_args Object - An object containing arbitrary key-value pairs to be passed to the task function defined in the execute string as arguments. Types of keys and values are entirely dependant on the load_data definition.
execute_args Object - An object containing arbitrary key-value pairs to be passed to the task function defined in the execute string as arguments. Types of keys and values are entirely dependant on the execute definition.

Notes

  • Ensure the JWT token used for authentication has sufficient permissions to access the dataset.