The arcgis.graph
module contains classes and functions for working with ArcGIS Knowledge graphs. The available
functions allow for searching and querying the graph data, and viewing the data model of the graph database.
Knowledge graphs consist of entities and the relationships between them, each of which can contain properties which describe their attributes. The data model of the knowledge graph can show you which entities, relationships, and properties are in your database, along with other information about the graph. Performing a search or openCypher query on the graph will return results from the database based on the search or query terms provided.
Note
Applications based on ArcGIS API for Python version 2.0.1 can only communicate with knowledge graphs in an ArcGIS Enterprise 10.9.1 or 11.0 deployment. ArcGIS Enterprise 11.1 includes breaking changes for knowledge graphs. Only applications based on ArcGIS API for Python version 2.1.0 or later will be able to communicate with knowledge graphs in an Enterprise 11.1 deployment. See the ArcGIS Enterprise Knowledge Server documentation for more details.
KnowledgeGraph
- class arcgis.graph.KnowledgeGraph(url, *, gis=None)
Provides access to the Knowledge Graph service data model and properties, as well as methods to search and query the graph.
Parameter
Description
url
Knowledge Graph service URL
gis
an authenticated
arcgis.gis.GIS
object.# Connect to a Knowledge Graph service: gis = GIS(url="url",username="username",password="password") knowledge_graph = KnowledgeGraph(url, gis=gis)
- apply_edits(adds=[], updates=[], deletes=[], input_transform=None, cascade_delete=False, cascade_delete_provenance=False)
Allows users to add new graph entities/relationships, update existing entities/relationships, or delete existing entities/relationships. For details on how the dictionaries for each of these operations should be structured, please refer to the samples further below.
Note
objectid values are not supported in dictionaries for apply_edits
Parameter
Description
adds
Optional list of dicts. The list of objects to add to the graph, represented in dictionary format.
updates
Optional list of dicts. The list of existent graph objects that are to be updated, represented in dictionary format.
deletes
Optional list of dicts. The list of existent objects to remove from the graph, represented in dictionary format.
input_transform
Optional dict. Allows a user to specify custom quantization parameters for input geometry, which dictate how geometries are compressed and transferred to the server. Defaults to lossless WGS84 quantization.
cascade_delete
Optional boolean. When True, relationships connected to entities that are being deleted will automatically be deleted as well. When False, these relationships must be deleted manually first. Defaults to False.
cascade_delete_provenance
Optional boolean. When True, deleting entities/relationships or setting their property values to null will result in automatic deletion of associated provenance records. When False, apply_edits() will fail if there are provenance records connected to entities/relationships intended for deletion or having their properties set to null.
# example of an add dictionary- include all properties { "_objectType": "entity", "_typeName": "Person", "_id": "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX}" "_properties": { "name": "PythonAPILover", "hometown": "Redlands", } } # update dictionary- include only properties being changed { "_objectType": "entity", "_typeName": "Person", "_id": "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX}" "_properties": { "hometown": "Lisbon", } } # delete dictionary- pass a list of id's to be deleted { "_objectType": "entity", "_typeName": "Person", "_ids": ["{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX}"] }
- Returns:
A dict showing the results of the edits.
- constraint_rule_adds(rules)
Adds constraint rules for entities & relationships to the data model.
Parameter
Description
rules
Required list of dicts. The dictionaries defining the constraint rules to be added. See below for an example of the structure.
# Create a constraint rule and add it to the Knowledge Graph's data model. person = {"set": ["Person"]} works_at = {"set": ["WorksAt"]} company = {"set_complement": ["Company"]} relationship_exclusion_rule = { "origin_entity_types": person, "relationship_types": works_at, "destination_entity_types": company } constraint_rule = { "name": "PersonCS", "alias": "officespace", "disabled": False, "relationship_exclusion_rule": relationship_exclusion_rule } knowledge_graph.constraint_rule_adds([constraint_rule])
- Returns:
A dict showing the results of adding the rule(s).
- constraint_rule_deletes(rule_names)
Deletes existing constraint rules for entities & relationships from the data model.
Parameter
Description
rule_names
Required list of strings. The names of the constraint rules to be deleted, as defined in a rule’s ‘name’ attribute.
# Delete a constraint rule from the Knowledge Graph's data model. knowledge_graph.constraint_rule_deletes(["constraint_rule_1"])
- Returns:
A dict showing the results of deleting the rule(s).
- constraint_rule_updates(rules)
Update constraint rules for entities & relationships in the data model.
Parameter
Description
rules
Required list of dicts. The dictionaries defining the constraint rules to be updated. See below for an example of the structure.
# Update a constraint rule in the Knowledge Graph's data model. constraint_rule = { "name": "PersonCS", "alias": "officespace", "disabled": False, } mask = { "update_name": False, "update_alias": True, "update_disabled": True } relationship_exclusion_rule_update = { "update_origin_entity_types": { "add_named_types": ["animal"], "remove_named_types": ["person"] }, "update_relationship_types": { "add_named_types": ["lives_in"], "remove_named_types": ["works_at"] }, "update_destination_entity_types": { "add_named_types": ["habitat"], "remove_named_types": ["company"] } } constraint_rule_update = { "rule_name": "PersonCS", "mask": mask, "constraint_rule": constraint_rule, "relationship_exclusion_rule_update": relationship_exclusion_rule_update } knowledge_graph.constraint_rule_updates([constraint_rule_update])
- Returns:
A dict showing the results of updating the rule(s).
- graph_property_adds(type_name, graph_properties)
Adds properties to a named type in the data model
Learn more about adding properties in a knowledge graph
Parameter
Description
type_name
Required string. The entity or relationship type to which the properties will be added.
graph_properties
Required list of dicts. The list of properties to add to the named type, represented in dictionary format.
# example of a shape property to be added to a named type { "name": "MyPointGeometry", "alias": "MyPointGeometry", "fieldType": "esriFieldTypeGeometry", "geometryType": "esriGeometryPoint", "hasZ": False, "hasM": False, "nullable": True, "editable": True, "visible": True, "required": False, "isSystemMaintained": False, "role": "esriGraphPropertyRegular" } # example of an integer property to be added to a named type { "name": "MyInt", "alias": "MyInt", "fieldType": "esriFieldTypeInteger", "nullable": True, "editable": True, "defaultValue": 123, "visible": True, "required": False, "isSystemMaintained": False, "role": "esriGraphPropertyRegular", "domain": "MyIntegerDomain" }
- Returns:
A dict showing the results of the property adds.
- graph_property_delete(type_name, property_name)
Delete a property for a named type in the data model
Learn more about deleting properties in a knowledge graph
Parameter
Description
type_name
Required string. The entity or relationship type containing the property to be deleted.
property_name
Required string. The property to be deleted.
# Delete a named type's property in the data model delete_result = knowledge_graph.graph_property_delete("Person", "Address")
- Returns:
A dict showing the results of the property delete.
- graph_property_index_adds(type_name, field_indexes)
Adds indexes to a field or multiple fields associated with a named type in the data model.
Learn more about adding graph property indexes in a knowledge graph
Parameter
Description
type_name
Required string. The entity or relationship type to add the indexes to.
field_indexes
Required list of dicts. The indexes to add for the type. See below for an example of the structure.
# Add a list of index dicts to fields for a Knowledge Graph type add_result = knowledge_graph.graph_property_index_adds( "Project", [ { "name" : "title", "isAscending": True, "isUnique": True, "fields": ["title"] } ] )
- Returns:
A dict showing the results of adding the indexes.
- graph_property_index_deletes(type_name, field_indexes)
Deletes indexes from fields associated with a named type in the data model.
Learn more about deleting graph property indexes from a knowledge graph
Parameter
Description
type_name
Required string. The entity or relationship type to delete the field indexes from.
field_indexes
Required list of strings. The field indexes to delete from the type. See below for an example of the structure.
# Delete a list of field index dicts from a Knowledge Graph type delete_result = knowledge_graph.graph_property_index_deletes("Project", ["title"])
- Returns:
A dict showing the results of deleting the indexes.
- graph_property_update(type_name, property_name, graph_property, mask)
Updates a property for a named type in the data model
Learn more about updating properties in a knowledge graph
Parameter
Description
type_name
Required string. The entity or relationship type containing the property to be updated.
property_name
Required string. The property to be updated.
graph_property
Required dict. The graph property to be updated, represented in dictionary format.
mask
Required dict. A dictionary representing the properties of the field to be updated.
# example of a shape property to be updated { "name": "MyPointGeometry", "alias": "MyPointGeometry", "fieldType": "esriFieldTypeGeometry", "geometryType": "esriGeometryPoint", "hasZ": False, "hasM": False, "nullable": True, "editable": True, "visible": True, "required": False, "isSystemMaintained": False, "role": "esriGraphPropertyRegular" } # example: update the property's alias { "update_alias": True } # OR { "update_name": False, "update_alias": True, "update_field_type": False, "update_geometry_type": False, "update_default_value": False, "update_nullable": False, "update_editable": False, "update_visible": False, "update_required": False, "update_has_z": False, "update_has_m": False, "update_domain:" False }
- Returns:
A dict showing the results of the property update.
- named_object_type_adds(entity_types=[], relationship_types=[])
Adds entity and relationship types to the data model
Learn more about adding named types to a knowledge graph
Parameter
Description
entity_types
Optional list of dicts. The list of entity types to add to the data model, represented in dictionary format.
relationship_types
Optional list of dicts. The list of relationship types to add to the data model, represented in dictionary format.
# example of a named type to be added to the data model { "name": "Person", "alias": "Person", "role": "esriGraphNamedObjectRegular", "strict": False, "properties": { "Name": { "name": "Name", "alias": "Name", "fieldType": "esriFieldTypeString", "editable": True, "visible": True, "required": False, "isSystemMaintained": False, "role": "esriGraphPropertyRegular" }, "Nickname": { "name": "Nickname", "alias": "Nickname", "fieldType": "esriFieldTypeString", "editable": True, "visible": True, "required": False, "isSystemMaintained": False, "role": "esriGraphPropertyRegular" } } }
- Returns:
A dict showing the results of the named type adds.
- named_object_type_delete(type_name)
Deletes an entity or relationship type in the data model
Learn more about deleting named types in a knowledge graph
Parameter
Description
type_name
Required string. The named type to be deleted.
# Delete a named type in the data model delete_result = knowledge_graph.named_object_type_delete("Person")
- Returns:
A dict showing the results of the named type delete.
- named_object_type_update(type_name, named_type_update, mask)
Updates an entity or relationship type in the data model
Learn more about updating named types in a knowledge graph
Parameter
Description
type_name
Required string. The named type to be updated.
named_type_update
Required dict. The entity or relationship type to be updated, represented in dictionary format.
mask
Required dict. A dictionary representing the properties of the named type to be updated.
# example of a named type to be updated { "name": "Person", "alias": "Person", "role": "esriGraphNamedObjectRegular", "strict": False } # update the named type's alias: { "update_alias": True } # OR { "update_name": False, "update_alias": True, "update_role": False, "update_strict": False }
- Returns:
A dict showing the results of the named type update.
- query(query)
Queries the Knowledge Graph using openCypher
Learn more about querying a knowledge graph
Parameter
Description
query
Required String. Allows you to return the entities and relationships in a graph, as well as the properties of those entities and relationships, by providing an openCypher query.
# Perform an openCypher query on the knowledge graph query_result = knowledge_graph.query("MATCH path = (n)-[r]-(n2) RETURN path LIMIT 5")
- Returns:
List[list]
- query_streaming(query, input_transform=None, bind_param=None, include_provenance=False)
Query the graph using an openCypher query. Allows for more customization than the base query() function. Creates a generator of the query results, from which users can access each row or add them to a list. See below for example usage.
Parameter
Description
query
Required String. Allows you to return the entities and relationships in a graph, as well as the properties of those entities and relationships, by providing an openCypher query.
input_transform
Optional dict. Allows a user to specify custom quantization parameters for input geometry, which dictate how geometries are compressed and transferred to the server. Defaults to lossless WGS84 quantization.
bind_param
Optional dict. The bind parameters used to filter query results. Key of each pair is the string name for it, which is how the parameter can be referenced in the query. The value can be any “primitive” type value that may be found as an attribute of an entity or relationship (e.g., string, double, boolean, etc.), a list, an anonymous object (a dict), or a geometry.
Anonymous objects and geometries can be passed in as either their normal Python forms, or following the format found in Knowledge Graph entries (containing an “_objectType” key, and “_properties” for anonymous objects).
Note: Including bind parameters not used in the query will cause queries to yield nothing on ArangoDB based services, while Neo4j based services will still produce results.
include_provenance
Optional boolean. When True, provenance entities (metadata) will be included in the query results. Defaults to False.
# Get a list of all query results query_gen = knowledge_graph.query_streaming("MATCH path = (n)-[r]-(n2) RETURN path LIMIT 5") results = list(gen) # Grab one result at a time query_gen = knowledge_graph.query_streaming("MATCH path = (n)-[r]-(n2) RETURN path LIMIT 5") first_result = next(query_gen) second_result = next(query_gen)
- search(search, category='both')
Allows for the searching of the properties of entities, relationships, or both in the graph using a full-text index.
Learn more about searching a knowledge graph
Parameter
Description
search
Required String. The search to perform on the Knowledge Graph.
category
Optional String. The category is the location of the full text search. This can be isolated to either the entities or the relationships. The default is to look in both.
The allowed values are: both, entities, relationships, both_entity_relationship, and meta_entity_provenance. Both and both_entity_relationship are functionally the same.
Note
Check the service definition for the Knowledge Graph service for valid values of category. Not all services support both and both_entity_relationship.
#Perform a search on the knowledge graph search_result = knowledge_graph.search("cat") # Perform a search on only entities in the knowledge graph searchentities_result = knowledge_graph.search("cat", "entities")
- Returns:
List[list]
- sync_data_model()
Synchronizes the Knowledge Graph Service’s data model with any changes made in the database. Will return any errors or warnings from the sync.
# Synchronize the data model sync_result = knowledge_graph.sync_data_model()
- update_search_index(adds=None, deletes=None)
Allows users to add or delete search index properties for different entities and relationships from the graph’s data model. Can only be existent properties for a given entity/relationship. Note that an empty dictionary result indicates success.
Parameter
Description
adds
Optional dict. See below for structure. The properties to add to the search index, specified by entity/relationship.
deletes
Optional dict. See below for structure. The properties to delete from the search index, specified by entity/relationship.
# example of an adds or deletes dictionary { "Entity1" : { "property_names": ["prop1", "prop2"]}, "Entity2" : {"property_names": ["prop1"]}, "RelationshipType1" : { "property_names": ["prop1", "prop2"]}, "RelationshipType2" : {"property_names": ["prop1"]}, }
- Returns:
A dict. Empty dict indicates success, errors will be returned in the dict.