Community
Select to view content in your preferred language

Query ArcGIS Knowledge Graphs from Map Pop-ups with Arcade

36
0
yesterday
AdamMartin
by Esri Contributor
Esri Contributor
0 0 36
yesterday

ArcGIS Arcade can be used to query ArcGIS Knowledge Graphs directly from custom pop-ups in web maps, map apps, link charts, ArcGIS Pro, ArcGIS AllSource, ArcGIS Knowledge Studio, and Map Viewer. This lets analysts enrich a selected feature, entity, or relationship with connected context from an enterprise knowledge graph—without moving users out of their existing map or link-chart workflow.

This pattern is useful when a feature layer contains only part of the operational picture, but the broader context lives in a knowledge graph. A pop-up can match the selected feature to a graph entity by unique ID, use the selected feature’s geometry in a spatial graph query, summarize connected entities, or generate a URL that opens the related entity in Knowledge Studio.

In this context, “side-loading context” means retrieving related graph information at click time and displaying it in a pop-up, rather than copying graph-derived attributes into the feature layer.

There are two common patterns: first, feature-layer pop-ups can use a shared ID, attribute, or geometry to find related entities in a knowledge graph; second, knowledge graph layer pop-ups can start from the selected entity or relationship and query additional connected context from the same graph.

What you’ll learn

  • How to use ArcGIS Arcade to query ArcGIS Knowledge Graphs from custom pop-ups.
  • How to match feature-layer pop-ups to graph entities using shared IDs, attributes, or geometry.
  • How to query the same graph from a knowledge graph layer or link chart using $graph.
  • How to format graph query results as pop-up text, tables, links, or summaries.
  • How to generate Knowledge Studio URLs from Arcade expressions.

When to use Arcade graph pop-ups

Use this pattern when your map layer shows the operational feature, but related context lives in an ArcGIS Knowledge Graph. Common examples include finding suppliers, assets, facilities, parcels, customers, documents, or other connected entities related to a selected feature.

  • Run spatial graph queries from a selected polygon, route, facility, or incident area.
  • Summarize upstream and downstream relationships.
  • Open selected or related entities in ArcGIS Knowledge Studio.
  • Enrich existing maps and apps without duplicating graph-derived attributes into feature layers.

Prerequisites

  • ArcGIS Enterprise 11.3 or later for Arcade knowledge graph functions.
  • ArcGIS Pro 3.3 or later, ArcGIS AllSource, Map Viewer, ArcGIS Knowledge Studio, or another supported map or link-chart experience.
  • Access to an ArcGIS Knowledge Graph.
  • A shared identifier, selected geometry, or knowledge graph layer entity that can be used as the query input.
  • Appropriate permissions to access the feature layer, knowledge graph, and Knowledge Studio project.

Canonical workflow

  1. Identify the knowledge graph using KnowledgeGraphByPortalItem() or $graph.
  2. Capture the selected feature, entity, relationship, attribute, or geometry.
  3. Use querygraph() to retrieve connected entities, relationships, or spatial matches.
  4. Format the query results as readable pop-up content.
  5. Return a dictionary that ArcGIS renders in the pop-up.

Let’s walk through an example. Suppose you have a feature layer showing a hurricane prediction cone overlaid on a map of key supplier facilities. In addition, you maintain more detailed information about your suppliers—and their suppliers—within a separate knowledge graph in ArcGIS. Now, when you click on a weather-related feature, your pop-up can instantly run a spatial query against your knowledge graph. This allows you to identify not only all your tier 1 suppliers located within the affected area, but also their upstream suppliers and any parts that may need to be pre-positioned (shipped earlier) in preparation for the hurricane.

You can also configure your pop-up to run multiple queries at once. For example, the same pop-up could display a summary of all downstream products, key customers, and expected revenue that might be impacted in the next 30 days if that supplier’s facility is disrupted by the hurricane.

Custom pop-ups can also generate Knowledge Studio URLs that open the selected feature, matched graph entity, or related entity for deeper exploration.

How Arcade graph pop-ups work

Starting with ArcGIS Enterprise 11.3 and ArcGIS Pro 3.3, Arcade expressions can query ArcGIS Knowledge Graphs from custom pop-ups in maps and link charts. These pop-ups can be configured for feature layers or knowledge graph layers in ArcGIS Pro, ArcGIS AllSource, ArcGIS Knowledge Studio, Map Viewer, and web map applications.

The pop-up uses Arcade graph functions to send information from the selected feature, entity, or relationship into a graph query. The query can return connected entities, relationship details, calculated summaries, spatial matches, or formatted output that appears directly in the pop-up.

For feature-layer pop-ups, the selected feature is typically matched to a knowledge graph entity using a shared GUID, asset ID, facility ID, parcel ID, or other unique attribute. The pop-up can also pass the selected feature’s geometry into a spatial graph query to find graph entities that intersect, fall within, or relate to that area.

For knowledge graph layer pop-ups, the selected entity or relationship is already the starting point. Arcade can use that selection to query additional graph context, summarize connected data, or generate a Knowledge Studio URL that opens the related entity for deeper exploration.

Arcade Pattern for Querying ArcGIS Knowledge Graphs from Pop-ups

Most Arcade-based Knowledge Graph pop-ups follow the same basic pattern: identify the graph, define the selected feature or entity as the input, run a graph query, format the results, and return a pop-up-ready dictionary. Let's walk through each step.

Step 1 — Identify the Knowledge Graph to Query

In Arcade, “connecting” to a knowledge graph means identifying the graph you want to query. Use KnowledgeGraphByPortalItem() to reference a graph by portal item. If the pop-up is built on a Knowledge Graph Layer and queries the same graph, you can skip this step and use $graph directly in the query.

  • If the graph is stored in another ArcGIS Enterprise portal, users may be prompted to sign in to that portal when the map or link chart opens.
  • Make sure the graph data model—entity types, relationship types, and properties—aligns with the identifiers, attributes, or geometry used by the pop-up expression.

Example code: reference the knowledge graph

// Option A: query a target graph by portal item
var portalUrl = "https://[YOUR_ORG_PORTAL_URL]/portal";
var graphItemId = "[KNOWLEDGE_GRAPH_ITEM_ID]";
var kg = KnowledgeGraphByPortalItem(Portal(portalUrl), graphItemId);

// Option B: query the same graph as the selected graph layer
var kg = $graph;

Step 2 — Identify the Feature, Entity or Geometry You Want to Query

Next, decide what the pop-up will pass into the graph query: a feature attribute, the selected feature’s geometry, or the selected graph entity or relationship.

For feature-layer pop-ups, this usually means:

  • Choosing a shared identifier, such as a GUID, asset ID, facility ID, parcel ID, or other unique attribute.
  • Using that value to find the corresponding entity or connected context in the knowledge graph.

 

Query Patterns

Description

Example Use Cases

Match by a Unique ID

Match a selected feature to a graph entity using a shared ID such as a GUID, asset ID, facility ID, or parcel ID.

 

·   Fetch connected entities and properties

·   Aggregate statistics about groups of connected entities

·   Aggregate statistics about properties of those connected entities

·   Find employees matching open roles, proximity, and skill criteria.

Match by Intersecting Shape

Use the selected feature’s geometry as an input to a spatial graph query that returns entities intersecting, contained within, or related to that shape.

 

·   Find downstream suppliers of suppliers within a selected polygon.

·   Aggregate statistics from properties on connected entities or relationships

 

Example code: capture the selected input

// Attribute-based input from a selected feature
var selectedId = $feature.[SHARED_ID_FIELD];
var params = { id: selectedId };

// Graph-layer input from a selected entity
var selectedGuid = $feature.globalid;

For graph-layer pop-ups, the selected entity is already the starting point, so the expression can typically use that entity’s GUID directly.

Graph queries can also use the selected feature’s geometry to filter results spatially, as in the supply chain example described above.

// Geometry-based input from a selected feature
var selectedGeom = Generalize($feature, 5000, true, 'meters');
var spatialParams = { feature_geom: selectedGeom };

querygraph(kg, "MATCH (s:Supplier) WHERE esri.graph.ST_Contains($feature_geom, s.shape) RETURN s.Name, s.globalid", {'feature_geom': $feature}

This step anchors the query to the feature, entity, relationship, or geometry the user selected.

Step 3 — Write the Graph Query Logic

Define the insight the pop-up should return. Common query operations include:

  • Retrieving neighboring entities, such as suppliers, assets, facilities, people, or documents.
  • Traversing multi-hop relationships, such as upstream suppliers or downstream customers.
  • Filtering by status, time period, category, relationship type, or spatial relevance.
  • Calculating summaries such as counts, totals, rankings, risk scores, or category lists.
  • Combining multiple graph queries into one pop-up response.

The goal is to turn connected graph data into a concise answer the user can understand at a glance.

Example code: run relationship and spatial graph queries

var results = querygraph(
  kg,
  "MATCH (start:EntityType {globalid: $id})-[:RELATIONSHIP_TYPE]->(related:EntityType) RETURN related.Name, related.globalid LIMIT 10",
  { id: selectedGuid }
);

var spatialResults = querygraph(
  kg,
  "MATCH (e:EntityType) WHERE esri.graph.ST_Contains($feature_geom, e.shape) RETURN e.Name, e.globalid",
  { feature_geom: selectedGeom }
);

Step 4 — Format the Results for the Pop‑up

After the query returns results, format them for the pop-up. Most expressions:

  • Build a dictionary with named sections or formatted output.
  • Format results as text, lists, small tables, or links.
  • Return one structured object that the ArcGIS pop-up engine can render.

This is where raw graph results become readable context for the selected map feature, entity, or link-chart element.

Example code: format graph results for display

var finalText = "";

for (var r in results) {
  var name = results[r][0];
  var guid = results[r][1];
  finalText += "<b>" + name + "</b><br>";
}

if (IsEmpty(finalText)) {
  finalText = "No related graph results found.";
}

Step 5 — Return the Final Dictionary

Finally, return the dictionary. ArcGIS reads the returned object and renders the formatted text, sections, tables, links, or controls in the pop-up.

Example code: return the pop-up content

return {
  type: 'text',
  text: finalText
};

Format ArcGIS Knowledge Graph Query Results in Pop-ups

Arcade expressions can format graph query results in several pop-up-friendly ways. Common patterns include:

  • Generate sections with expandable lists or tables of resulting related entities matching your pattern
  • Generate tables of resulting entities and statistics created using the query
  • Generate dynamic links to entities (starting in 11.4) or saved queries (starting in 12.0) in the Knowledge Studio web app using URL Parameters.

See example: Arcade_Graph_Pop-ups.mp4

AdamMartin_0-1783048582330.jpeg

Full Example: End-to-end Arcade Script

In this simple example, the graph query within the Arcade expression returns the Suppliers located within the polygon of a selected weather feature. The script also uses the Arcade geometry function - generalize - to simplify the shape of the selected polygon to improve performance of the spatial openCypher query.

This is an example of a query you could use in a Map with an independent Feature Service there for reference alongside a spatial Knowledge Graph layer, or the graph could not be present in the map at all!

//The portal item ID of the Knowledge Graph service (pid) and server url portal url (Change these)
var pid = "d03d80ca35c94cadb963f845acbd0de1"
var portal_url = " https://[YOUR_ORG_PORTAL_URL].com/portal/"
var kg = KnowledgeGraphByPortalItem(Portal(portal_url), pid)
 
// To simplify the polygon for better performance, we are using the Generalize function
var gen = Generalize($feature, 5000, true, 'meters')
 
var results = querygraph(kg, "MATCH (s:Supplier) WHERE esri.graph.ST_Contains($feature_geom, s.shape) RETURN s.Name, s.globalid", {'feature_geom': gen});
 
var final_str = "";
var cnt = 0
 
for (var r in results) {
  var name = results[r][0]
  var g_id = StandardizeGuid(results[r][1],'digits-hyphen')
  var studio_url = '<a href = ' + server_url + '/apps/knowledge-studio/main?id=' + pid + '&selectedContentId=dataExplorer&selectedContentElement=%7B' + g_id + '%7D&selectedContentInstruction=entity>'
  final_str = final_str + studio_url + " " + name + "</a><br>"
}
return {
   type : 'text',
text : final_str
}

AdamMartin_0-1783049751404.png

 

I plan follow this blog with some additional full sample queries, along with AI prompts to help you leverage LLMs to help you build your own Arcade + Graph queries. You can also go deeper by reviewing the Arcade Knowledge Graph function documentation.

0 Kudos
Contributors