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 the results of a query by its ID. If the download directory does not exist, it will be created. 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.
-
folder(str, default:'./results') –The directory where the results should be saved.
Returns:
-
str(None) –Path to the downloaded results.
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_all_kgs
Retrieve all available Knowledge Graphs.
This function fetches a list of all available Knowledge Graphs (KGs) that the user has access to, including their metadata such as kg_id, kg_name, kg_description, version_id, created_at timestamp, and published status.
Parameters:
-
include_unpublished(bool, default:False) –Include unpublished knowledge graphs. Defaults to False.
-
include_instances(bool, default:False) –Include instance information for each KG. When True, each KG will include an 'instances' array with details about available instances (instance_id, instance_type, CPU/RAM, etc.). Defaults to False.
-
include_terminated(bool, default:False) –Include terminated instances in the response. Only applies when include_instances is True. Defaults to False.
Returns:
-
list(list) –A list of dictionaries, where each dictionary contains: - kg_id (str): Unique identifier for the knowledge graph - kg_name (str): Name of the knowledge graph - kg_description (str): Description of the knowledge graph - version_id (int): Current version ID - created_at (int): Creation timestamp (Unix epoch in milliseconds) - published (bool): Whether the KG is published - instances (list, optional): Available when include_instances=True. Each instance contains: - instance_id (str): Unique identifier for the instance - instance_type (str): Type/size of instance (e.g., "t3.medium") - is_terminated (bool): Whether the instance is terminated - default_instance (bool): Whether this is the default instance - org_id (int): Organization ID - created_at (int): Instance creation timestamp
Raises:
-
ResourceNotFoundError–Raised when no knowledge graphs are found.
-
AccessDeniedError–Raised when the user does not have permission to access the KGs.
-
RequestFailureException–Raised when the request fails due to an unexpected error.
Example
kg = PollyKG()
Get only published KGs
kgs = kg.get_all_kgs() for kg_info in kgs: ... print(f"{kg_info['kg_name']} (ID: {kg_info['kg_id']})") base kg v3 (ID: 14_base_kg_v3)
Get all KGs including unpublished ones with instance details
kgs_with_instances = kg.get_all_kgs( ... include_unpublished=True, ... include_instances=True, ... include_terminated=True ... ) for kg_info in kgs_with_instances: ... print(f"{kg_info['kg_name']} - {len(kg_info.get('instances', []))} instances")
get_query_results
Get the results of a query by its ID.
Parameters:
-
query_id(str) –The ID of the query whose results you want to get.
Returns:
-
dict(None) –Query result in parsed JSON format.
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
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
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
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
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.
submit_query
Submit a graph query on the specified KG version.
This function submits the query to Polly KG and returns the Query ID.
Parameters:
-
query(str) –The query string to be executed.
-
query_type(str, default:'CYPHER') –The query language type. Accepts "CYPHER".
Returns:
-
query_id(str) –Unique Identifier for the query submitted.
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()
submit_query()
get_query_status()
get_query_results()
download_query_results()
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()
{
"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"
}
]
}
}
}
}
get_all_kgs()
[
{
"kg_id": "14_base_kg_v3",
"kg_name": "base kg v3",
"kg_description": "Base KG version 3",
"version_id": 1,
"created_at": 1756115807076,
"published": true
},
{
"kg_id": "15_medical_kg",
"kg_name": "medical kg",
"kg_description": "Medical Knowledge Graph",
"version_id": 2,
"created_at": 1756120000000,
"published": true
}
]
# Get all KGs including unpublished ones with instance details
kgs_with_instances = kg.get_all_kgs(
include_unpublished=True,
include_instances=True,
include_terminated=True
)
print(kgs_with_instances)
[
{
"kg_id": "14_base_kg_v3",
"kg_name": "base kg v3",
"kg_description": "Base KG version 3",
"version_id": 1,
"created_at": 1756115807076,
"published": true,
"instances": [
{
"instance_id": "inst_abc123",
"instance_type": "t3.medium",
"is_terminated": false,
"default_instance": true,
"org_id": 1,
"created_at": 1756115807076
}
]
},
{
"kg_id": "15_medical_kg",
"kg_name": "medical kg",
"kg_description": "Medical Knowledge Graph",
"version_id": 2,
"created_at": 1756120000000,
"published": false,
"instances": [
{
"instance_id": "inst_xyz789",
"instance_type": "t3.large",
"is_terminated": false,
"default_instance": true,
"org_id": 1,
"created_at": 1756120000000
}
]
}
]