arcgis.graph module

KnowledgeGraph

class arcgis.graph.KnowledgeGraph(url: str, *, 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 GIS object.

# Connect to a Knowledge Graph service:

gis = GIS(url="url",username="username",password="password")

knowledge_graph = KnowledgeGraph(url, gis=gis)

add_domain(domain: CodedValueDomain | RangeDomain) → AddDomainResponse

Adds a domain to the knowledge graph data model.

Parameter	Description
domain	Required GraphDomain. The domain to be added to the data model.

from arcgis.graph import GraphDomain

graph.add_domain(
    CodedValueDomain(
        name="example_domain",
        coded_values=[CodedValue(name="Active", code="yes"), CodedValue(name="Inactive", code="no")],
        field_type="esriFieldTypeString",
        merge_policy_type="esriMergePolicyTypeDefaultValue",
        split_policy_type="esriSplitPolicyTypeDefaultValue",
    )
)

apply_edits(adds: Sequence[dict[str, Any] | Entity | Relationship] = [], updates: Sequence[dict[str, Any] | Entity | Relationship] = [], deletes: Sequence[dict[str, Any] | EntityDelete | RelationshipDelete] = [], input_transform: dict[str, Any] | Transform | None = None, cascade_delete: bool = False, cascade_delete_provenance: bool = False, as_dict: bool = True) → dict | ApplyEditsResponse

Allows users to add, update, and delete Entity and Relationship.

Note

objectid values are not supported in dictionaries for apply_edits

Parameter	Description
adds	Optional list of Entity or Relationship. The list of objects to add to the graph, represented in dictionary format.
updates	Optional list of Entity or Relationship. The list of existent graph objects that are to be updated, represented in dictionary format.
deletes	Optional list of EntityDelete or RelationshipDelete. The list of existent objects to remove from the graph, represented in dictionary format.
input_transform	Optional Transform. 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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import Entity, Relationship

add_entity = Entity(type_name="Company", properties={"name": "Esri"})
delete_relationship = DeleteRelationship(type_name="WorksAt", ids=[UUID("783bd422-3hfp-45c7-87aa-8adbbdac0a3d")])

graph.apply_edits(adds=[add_entity], deletes=[delete_relationship], as_dict=False)

Returns:

ApplyEditsResponse

constraint_rule_adds(rules: Sequence[dict[str, Any] | ConstraintRule], as_dict: bool = True) → dict | ConstraintRuleAddsResponse

Adds constraint rules for entities & relationships to the data model. RelationshipExclusionRule is a constraint rule.

Parameter	Description
rules	Required Sequence of RelationshipExclusionRule. Defines the constraint rules to be added.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import RelationshipExclusionRule

graph.constraint_rule_adds(
    rules=[
        RelationshipExclusionRule(
            name="OnlyPersonCanWorkAtCompany",
            origin_entity_types=SetOfNamedTypes(set_complement=["Person"]),
            relationship_types=SetOfNamedTypes(set=["WorksAt"]),
            destination_entity_types=SetOfNamedTypes(set=["Company"])
        )
    ],
    as_dict=False
)

Returns:

ConstraintRuleAddsResponse

constraint_rule_deletes(rule_names: Sequence[str], as_dict: bool = True) → dict | ConstraintRuleDeletesResponse

Deletes existing constraint rules for entities & relationships from the data model. RelationshipExclusionRule is a constraint rule.

Parameter	Description
rule_names	Required Sequence of strings. The names of the constraint rules to be deleted, as defined in a rule’s ‘name’ attribute.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Delete a constraint rule from the Knowledge Graph's data model.
graph.constraint_rule_deletes(["constraint_rule_1"], as_dict=False)

Returns:

ConstraintRuleDeletesResponse

constraint_rule_updates(rules: Sequence[dict[str, Any] | ConstraintRuleUpdate], as_dict: bool = True) → dict | ConstraintRuleUpdatesResponse

Update ConstraintRule for entities & relationships in the data model. RelationshipExclusionRule is a type of constraint rule.

Parameter	Description
rules	Required Sequence of RelationshipExclusionRuleUpdate. Defines the constraint rules to be updated.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import RelationshipExclusionRuleUpdate, ConstraintRule, ConstraintRuleMask, UpdateSetOfNamedTypes

graph.constraint_rule_updates(
    rules=[
        RelationshipExclusionRuleUpdate(
            rule_name="OnlyPersonCanWorkForCompany",
            mask=ConstraintRuleMask(update_name=True, update_alias=True),
            constraint_rule=ConstraintRule(
                name="PersonCanWorkForCompanyOrPark",
                alias="Person Can Work For Company or Park"
            )
        )
    ],
    as_dict=False
)

Returns:

ConstraintRuleUpdatesResponse

create_replica(replica_params: ReplicaRequest) → CreateReplicaResponse

Creates a replica of the knowledge graph service.

Parameter	Description
replica_params	Required ReplicaRequest. The parameters for creating the replica.

from arcgis.graph import ReplicaRequest, ReplicaFilters, StaticDefinition, EntityTypeReplicaDefinition, RelationshipTypeReplicaDefinition

replica_request = ReplicaRequest(
    replica_name="my_replica",
    replica_definition=ReplicaFilters(
        static_definition=StaticDefinition(
            entity_type_replica_definitions=[
                EntityTypeReplicaDefinition(
                    type_name="Person",
                    open_cypher_where_clause="WHERE age > 18"
                )
            ],
            relationship_type_replica_definitions=[
                RelationshipTypeReplicaDefinition(
                    type_name="WorksAt",
                    open_cypher_where_clause="WHERE startDate > '2020-01-01'"
                )
            ]
        )
    ),
    asynchronous=False,
)

replica_response = kg.create_replica(replica_request)
replica_data = replica_response.replica_data

Returns:

CreateReplicaResponse

property datamodel: dict

Returns the datamodel for the Knowledge Graph service

Returns:

dict

delete_domain(domain_name: str) → DeleteDomainResponse

Deletes an existing domain from the knowledge graph data model.

Parameter	Description
domain_name	Required string. The name of the domain to be deleted.

# Delete a domain from the Knowledge Graph's data model.
graph.delete_domain("StatusDomain")

export(timeout: int = 600) → ExportResponse

Exports the knowledge graph service definition in GeoParquet format.

Parameter	Description
timeout	Optional integer. The maximum time, in seconds, to wait for the export operation to complete. The default is 600 seconds.

Returns:

ExportResponse

# Export the knowledge graph service definition
export_response = graph.export(timeout=300)

classmethod fromitem(item)

Returns the Knowledge Graph service from an Item

get_replica_definition(replica_id: UUID | str) → ReplicaDefinitionResponse

Retrieves the definition of a replica.

Parameter	Description
replica_id	Required UUID or string. The ID of the replica to retrieve.

Returns:

ReplicaDefinitionResponse

graph_property_adds(type_name: str, graph_properties: Sequence[dict[str, Any] | GraphProperty], as_dict: bool = True) → dict | PropertyAddsResponse

Adds set of GraphProperty 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 Sequence of GraphProperty. The Sequence of properties to add to the named type.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import GraphProperty

graph.graph_property_adds(type_name="Vehicle", graph_properties=[GraphProperty(name="year")])

Returns:

PropertyAddsResponse

graph_property_delete(type_name: str, property_name: str, as_dict: bool = True) → dict | PropertyDeleteResponse

Delete a GraphProperty 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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Delete a named type's property in the data model
delete_result = knowledge_graph.graph_property_delete("Person", "Address", as_dict=False)

Returns:

PropertyDeleteResponse

graph_property_index_adds(type_name: str, field_indexes: Sequence[dict[str, Any] | FieldIndex], as_dict: bool = True) → dict | IndexAddsResponse

Adds one or more FieldIndex 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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import FieldIndex

graph.graph_property_index_adds(
    type_name="Person",
    field_indexes=[FieldIndex(name="name_index", is_ascending=True, is_unique=False, fields=["name"])],
    as_dict=False
)

Returns:

IndexAddsResponse

graph_property_index_deletes(type_name: str, field_indexes: Sequence[str], as_dict: bool = True) → dict | IndexDeletesResponse

Deletes one or more FieldIndex 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 Sequence of strings. The field indexes to delete from the type.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Delete field indexes from a Knowledge Graph type
delete_result = graph.graph_property_index_deletes("Project", ["title"], as_dict=False)

Returns:

IndexDeletesResponse

graph_property_update(type_name: str, property_name: str, graph_property: dict[str, Any] | GraphProperty, mask: dict[str, Any] | GraphPropertyMask, as_dict: bool = True) → dict | PropertyUpdateResponse

Updates a GraphProperty 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 GraphProperty. The graph property to be updated.
mask	Required GraphPropertyMask. The properties of the field to be updated.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import GraphProperty, GraphPropertyMask

graph.graph_property_update(
    type_name="Vehicle",
    property_name="year",
    graph_property=GraphProperty(name="year", alias="year_made"),
    mask=GraphPropertyMask(update_alias=True),
    as_dict=False
)

Returns:

PropertyUpdateResponse

named_object_type_adds(entity_types: Sequence[dict[str, Any] | EntityType] = [], relationship_types: Sequence[dict[str, Any] | RelationshipType] = [], as_dict: bool = True) → dict | NamedObjectTypeAddsResponse

Adds EntityType and RelationshipType to the data model

Learn more about adding named types to a knowledge graph

Parameter	Description
entity_types	Optional list of EntityTypes. The list of entity types to add to the data model, represented in dictionary format.
relationship_types	Optional list of RelationshipTypes. The list of relationship types to add to the data model, represented in dictionary format.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import EntityType, RelationshipType, GraphProperty

entity_type_add = EntityType(name="Vehicle", properties={"make": GraphProperty(name="make")})
relationship_type_add = RelationshipType(name="Drives")

graph.named_object_type_adds(entity_types=[entity_type_add], relationship_types=[relationship_type_add], as_dict=False)

Returns:

NamedObjectTypeAddsResponse

named_object_type_delete(type_name: str, as_dict: bool = True) → dict | NamedObjectTypeDeleteResponse

Deletes an EntityType or RelationshipType 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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Delete a named type in the data model
delete_result = graph.named_object_type_delete("Person")

Returns:

NamedObjectTypeDeleteResponse

named_object_type_update(type_name: str, named_type_update: dict[str, Any] | EntityType | RelationshipType, mask: dict[str, Any] | NamedObjectTypeMask, as_dict: bool = True) → dict | NamedObjectTypeUpdateResponse

Updates an EntityType or RelationshipType 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 Union[EntityType, RelationshipType]. The entity or relationship type to be updated.
mask	Required NamedObjectTypeMask. The properties of the named type to be updated.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import EntityType, NamedObjectTypeMask

type_update = EntityType(name="Vehicle", alias="Car")

graph.named_object_type_update(
    type_name="Vehicle",
    named_type_update=type_update,
    mask=NamedObjectTypeMask(update_alias=True),
    as_dict=False
)

Returns:

NamedObjectTypeUpdateResponse

property properties: InsensitiveDict

Returns the properties of the Knowledge Graph service

query(query: str) → List[dict]

Deprecated since version 2.4.1: Removed in: 3.0.0. Use query_streaming instead.

Deprecated since version 2.4.1: Removed in: 3.0.0. Use query_streaming instead.

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.

Returns:

List[list]

# Perform an openCypher query on the knowledge graph
query_result = knowledge_graph.query("MATCH path = (n)-[r]-(n2) RETURN path LIMIT 5")

query_data_model(as_dict: bool = True) → dict | GraphDataModel

Returns the datamodel for the Knowledge Graph service

Parameter	Description
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Query knowledge graph data model
knowledge_graph.query_data_model(as_dict=False)

Returns:

GraphDataModel

query_streaming(query: str, input_transform: dict[str, Any] | Transform | None = None, bind_param: dict[str, Any] = {}, include_provenance: bool = False, as_dict: bool = True, as_df: bool = False) → Generator[Sequence[Any], None, None] | DataFrame

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 or Transform. 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.
as_df	Optional boolean. When True, returns all results in a pandas DataFrame instead of a generator. 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)

Returns:

A Generator[Sequence[Any], None, None] or pandas DataFrame when as_df is True.

property replicas: list[ReplicaInfoResponse]

Retrieves a list of ReplicaInfoResponse corresponding to each existent replica of the knowledge graph service.

search(search: str, category: str = 'both', as_dict: bool = True) → List[Sequence[Any]]

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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

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
for search_result in knowledge_graph.search("cat", as_dict=False):
    print(search_result)

# Perform a search on only entities in the knowledge graph
for searchentities_result in knowledge_graph.search("cat", "entities", as_dict=False):
print(searchentities_result)

Returns:

Generator[Sequence[Any], None, None]

sync_data_model(as_dict: bool = True) → dict | SyncDataModelResponse

Synchronizes the Knowledge Graph Service’s data model with any changes made in the database. Will return any errors or warnings from the sync.

Parameter	Description
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

# Synchronize the data model
sync_result = knowledge_graph.sync_data_model(as_dict=False)

Returns:

SyncDataModelResponse

synchronize_replica(sync_params: SynchronizeReplicaRequest) → SynchronizeReplicaResponse

Synchronizes a replica with the knowledge graph service.

Parameter	Description
sync_params	Required SynchronizeReplicaRequest. The parameters for synchronizing the replica.

from arcgis.graph.replica_sync_types import SynchronizeReplicaRequest, ReplicaSnapshot, SyncDownloadParameters

sync_request = SynchronizeReplicaRequest(
    replica_id="123e4567-e89b-12d3-a456-426614174000",
    download_parameters=SyncDownloadParameters(
        replica_snapshot=ReplicaSnapshot()
    )
)

sync_response = kg.synchronize_replica(sync_request)
sync_data = sync_response.sync_data

Returns:

SynchronizeReplicaResponse

unregister_replicas(replica_ids: Sequence[UUID | str]) → list[UnregisterReplicaResponse]

Unregisters one or more replicas of the knowledge graph service.

Parameter	Description
replica_ids	Required Sequence of UUIDs or strings. The IDs of the replicas to be unregistered.

replica_id_1 = "123e4567-e89b-12d3-a456-426614174000"
replica_id_2 = "123e4567-e89b-12d3-a456-426614174001"
unreg_response = kg.unregister_replicas([replica_id_1, replica_id_2])

Returns:

List of UnregisterReplicaResponse

update_domain(domain_update: GraphDomainUpdate) → UpdateDomainResponse

Updates an existing domain in the knowledge graph data model.

Parameter	Description
domain_update	Required GraphDomainUpdate. Contains the name of the domain, updated domain, and mask dictating which properties get updated.

from arcgis.graph import GraphDomain

graph.update_domain(
    name="StatusDomain",
    domain_update=GraphDomainUpdate(
        name = "StatusDomain",
        domain=GraphDomain(
            name="StatusDomain",
            domain_type="range",
            range_domain=RangeDomain(
                range=[0, 1]
            ),
            field_type="esriFieldTypeInteger",
            merge_policy_type="esriMergePolicyTypeDefaultValue",
            split_policy_type="esriSplitPolicyTypeDefaultValue",
        )
        mask = GraphDomainMask(
            update_type=True,
            update_domain=True,
            update_field_type=True
        )
    )
)

update_search_index(adds: dict[str, dict | SearchIndexProperties] = {}, deletes: dict[str, dict | SearchIndexProperties] = {}, as_dict: bool = True) → dict | UpdateSearchIndexResponse

Allows users to add or delete SearchIndexProperties for different EntityType and RelationshipType from the GraphDataModel. Can only be existent properties for a given entity/relationship type.

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.
as_dict	Optional Boolean. Determines whether the result is returned as a dictionary or an object. The default is True. False is recommended.

from arcgis.graph import SearchIndexProperties

graph.update_search_index(
    adds={"Person": SearchIndexProperties(property_names=["name"])},
    as_dict=False
)

Returns:

UpdateSearchIndexResponse

Data Model Types

Graph Types