Skip to content

PollyKG

The PollyKG class provides an interface to interact with the Polly Knowledge Graph (KG) API. It enables users to execute and manage Cypher queries, retrieve node and relationship data, and analyze graph structures efficiently. This class simplifies access to the KG engine, allowing seamless querying and data exploration. It is designed for users who need to extract insights from complex graph-based datasets.

Parameters:

  • token (str, default: None ) –

    Authentication token from polly

Usage

from polly.polly_kg import PollyKG

kg = PollyKG(token)

download_query_results

download_query_results(query_id)

Download the results of a query by its ID. The results will be saved in a ./results directory/query_id.json with the filename as query_id.json.

Parameters:

  • query_id (str) –

    The ID of the query whose results you want to download.

Raises:

  • InvalidParameterException

    If the query_id is empty or None.

  • QueryFailedException

    If query execution failed.

  • RequestFailureException

    If the request fails due to an unexpected error.

get_query_status

get_query_status(query_id)

Fetch the status of a submitted query.

Parameters:

  • query_id (str) –

    Unique ID of the submitted query.

Returns:

  • dict ( dict ) –

    A dictionary containing current status of the query (e.g., "IN_PROGRESS", "COMPLETED").

Raises:

  • InvalidParameterException

    If query_id is not provided.

get_schema

get_schema()

Retrieve the schema of the Polly Knowledge Graph.

Returns:

  • dict ( dict ) –

    A dictionary containing schema information about the graph, such as node types, relationship types, and other metadata.

Raises:

  • ResourceNotFoundError

    Raised when the specified graph schema does not exist.

  • AccessDeniedError

    Raised when the user does not have permission to access the graph schema.

  • RequestFailureException

    Raised when the request fails due to an unexpected error.

get_summary

get_summary()

Retrieve a summary of the Polly Knowledge Graph.

Returns:

  • dict ( dict ) –

    A dictionary containing summary information about the graph, such as node counts, edge counts, and other metadata.

Raises:

  • ResourceNotFoundError

    Raised when the specified graph summary does not exist.

  • AccessDeniedError

    Raised when the user does not have permission to access the graph summary.

  • RequestFailureException

    Raised when the request fails due to an unexpected error.

run_query

run_query(query, query_type='CYPHER')

Execute a graph query on the specified KG version.

This function submits the query to Polly KG, tracks its status, and waits until it completes. Once complete, it returns the result.

Parameters:

  • query (str) –

    The query string to be executed.

  • query_type (str, default: 'CYPHER' ) –

    The query language type. Accepts "CYPHER".

Returns:

  • dict ( dict ) –

    Query result in parsed JSON format.

Raises:

  • InvalidParameterException

    If query is empty.

  • QueryFailedException

    If query execution fails.

Examples

PollyKG class of polly-python can be initialised using the code block below:-

import os
from polly.auth import Polly
from polly.polly_kg import PollyKG
token = os.environ['POLLY_REFRESH_TOKEN']
Polly.auth(token)
kg = PollyKG()

run_query()

results = kg.run_query("MATCH (n) RETURN count(*);")
Query submitted successfully. Query ID: 6e7723bf-5019-45de-91f5-cc515e99d827.

print(results)
{'results': [{'count(*)': 2178708}]}

get_query_status()

kg.get_query_status("6e7723bf-5019-45de-91f5-cc515e99d827")
{'status': 'COMPLETED'}

download_query_results()

kg.download_query_results("6e7723bf-5019-45de-91f5-cc515e99d827")
Results downloaded successfully to ./results/6e7723bf-5019-45de-91f5-cc515e99d827.json

get_summary()

kg.get_summary()
{
    "data": {
        "type": "kg_summary",
        "attributes": {
            "metadata": {
                "name": "summary",
                "kg_id": "demo_kg",
                "kg_version": "1",
                "last_updated": "2025-06-25T07:28:55Z",
                "computed_at": "2025-06-25T07:28:55Z"
            },
            "node_counts": {
                "Tissue": 113,
                "Go": 47995,
                "Disease": 29976,
                "Phenotype": 29870
            },
            "edge_counts": {
                "is_a_go": 40264,
                "part_of_go": 6737,
                "regulates_go": 3132,
                "has_part_go": 636
            },
            "totals": {
                "total_nodes": 107954,
                "total_edges": 50769,
                "node_types": 4,
                "edge_types": 4
            }
        }
    }
}

get_schema()

kg.get_schema()
  {
  "data": {
    "type": "kg_schema",
    "attributes": {
      "metadata": {
        "name": "schema",
        "kg_id": "demo_kg",
        "kg_version": "1",
        "last_updated": "2025-06-25T07:28:55Z",
        "computed_at": "2025-06-25T07:28:55Z"
      },
      "node_types": [
        "Disease",
        "Drug",
        "Gene"
      ],
      "edge_types": [
        "connects",
        "associated",
        "related"
      ],
      "nodes": {
        "Disease": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "name",
              "type": "string"
            }
          ]
        },
        "Drug": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "name",
              "type": "string"
            }
          ]
        },
        "Gene": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "symbol",
              "type": "string"
            }
          ]
        }
      },
      "edges": {
        "connects": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "connection_type",
              "type": "string"
            }
          ],
          "connections": [
            {
              "from": "Tissue",
              "to": "Tissue Level"
            }
          ]
        },
        "associated": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "association_type",
              "type": "string"
            }
          ],
          "connections": [
            {
              "from": "Phenotype",
              "to": "Phenotype"
            }
          ]
        },
        "related": {
          "properties": [
            {
              "name": "id",
              "type": "string"
            },
            {
              "name": "relation_type",
              "type": "string"
            }
          ],
          "connections": [
            {
              "from": "Phenotype",
              "to": "Phenotype"
            }
          ]
        }
      }
    }
  }