O ArcGIS Arcade pode ser usado para consultar ArcGIS Knowledge Graphs diretamente de pop-ups personalizados em mapas web, aplicativos de mapa, gráficos de ligação dentro de muitas aplicações ArcGIS, como ArcGIS Pro, ArcGIS AllSource, ArcGIS Knowledge Studio e dentro de mapas no Map Viewer, Dashboards e Experience Builder. Isso permite que analistas enriqueçam uma feição, entidade ou relacionamento selecionado com contexto conectado de um grafo de conhecimento empresarial—sem tirar os usuários do fluxo de trabalho existente no mapa ou gráfico de ligação.
Esse padrão é útil quando uma camada de feição contém apenas parte do quadro operacional, mas o contexto mais amplo está em um grafo de conhecimento. Um pop-up pode corresponder a feição selecionada a uma entidade do grafo por ID único, usar a geometria da feição selecionada em uma consulta espacial do grafo, resumir entidades conectadas ou gerar uma URL que abre a entidade relacionada no Knowledge Studio.
Neste contexto, “carregar contexto lateralmente” significa recuperar informações relacionadas do grafo no momento do clique e exibi-las em um pop-up, em vez de copiar atributos derivados do grafo para a camada de feição.
Existem dois padrões comuns: primeiro, pop-ups da camada de feição podem usar um ID compartilhado, atributo ou geometria para encontrar entidades relacionadas em um grafo de conhecimento; segundo, pop-ups da camada do grafo de conhecimento podem começar pela entidade ou relacionamento selecionado e consultar contexto adicional conectado do mesmo grafo.
O que você vai aprender
- Como usar ArcGIS Arcade para consultar ArcGIS Knowledge Graphs a partir de pop-ups personalizados.
- Como corresponder pop-ups da camada de feição a entidades do grafo usando IDs compartilhados, atributos ou geometria.
- Como consultar o mesmo grafo a partir de uma camada do grafo de conhecimento ou gráfico de ligação usando $graph.
- Como formatar resultados da consulta do grafo como texto do pop-up, tabelas, links ou resumos.
- Como gerar URLs do Knowledge Studio a partir de expressões Arcade.
Quando usar pop-ups Arcade com grafos
Use este padrão quando sua camada no mapa mostrar a feição operacional, mas o contexto relacionado estiver em um ArcGIS Knowledge Graph. Exemplos comuns incluem encontrar fornecedores, ativos, instalações, lotes, clientes, documentos ou outras entidades conectadas relacionadas a uma feição selecionada.
- Executar consultas espaciais no grafo a partir de um polígono selecionado, rota, instalação ou área de incidente.
- Resumir relacionamentos ascendentes e descendentes
- Resumir propriedades dessas entidades relacionadas ascendentes ou descendentes (soma, média etc.)
- Abrir entidades selecionadas ou relacionadas no ArcGIS Knowledge Studio.
- Fazer perguntas adicionais no ArcGIS Knowledge Studio sobre a entidade selecionada ou relacionada usando um parâmetro URL
- Enriquecer mapas e apps existentes sem duplicar atributos derivados do grafo nas camadas de feição.
Pré-requisitos
- ArcGIS Enterprise 11.3 ou superior para funções Arcade de knowledge graph em Pop-Ups web Map / Link Chart
- ArcGIS Pro 3.3 ou superior, ArcGIS AllSource, Map Viewer, ArcGIS Knowledge Studio ou outra experiência suportada de mapa ou gráfico de ligação.
- Acesso a um ArcGIS Knowledge Graph.
- Um identificador compartilhado, geometria selecionada ou entidade da camada do knowledge graph que possa ser usada como entrada da consulta.
- Permissões apropriadas para acessar a camada de feição, knowledge graph e projeto Knowledge Studio.
- ArcGIS Enterprise 12.1 para desbloquear URLs dinâmicos para consultas salvas, novos gráficos de ligação e outros fluxos avançados no Knowledge Studio a partir dos pop-ups
Fluxo canônico
- Identifique o knowledge graph usando KnowledgeGraphByPortalItem() ou $graph.
- Capture a feição selecionada, entidade, relacionamento, atributo ou geometria.
- Use querygraph() para recuperar entidades conectadas, relacionamentos ou correspondências espaciais.
- Formate os resultados da consulta como conteúdo legível para o pop-up.
- Retorne um dicionário que o ArcGIS renderiza no pop-up.
Exemplo completo: Script Arcade ponta a ponta
Vamos passar por um exemplo. Suponha que você tenha uma camada de feição mostrando um cone preditivo de furacão sobreposto em um mapa das principais instalações dos fornecedores. Além disso, você mantém informações mais detalhadas sobre seus fornecedores—e seus fornecedores—dentro de um knowledge graph separado no ArcGIS. Agora, quando você clica em uma feição relacionada ao clima, seu pop-up pode executar instantaneamente uma consulta espacial contra seu knowledge graph. Isso permite identificar não apenas todos os fornecedores tier 1 localizados na área afetada, mas também seus fornecedores ascendentes e quaisquer peças que possam precisar ser pré-posicionadas (enviadas antecipadamente) em preparação para o furacão.
Você também pode configurar seu pop-up personalizado para executar múltiplas consultas ao mesmo tempo. Por exemplo, o mesmo pop-up poderia exibir um resumo de todos os produtos descendentes, clientes-chave e receita esperada que poderiam ser impactados nos próximos 30 dias se a instalação desse fornecedor for interrompida pelo furacão.
O script Arcade exemplo abaixo mostra como você poderia usar em um Mapa com um Serviço de Feições independente lá para referência junto com uma camada espacial do Knowledge Graph, ou o grafo pode nem estar presente no mapa! A consulta ao grafo dentro da expressão Arcade retorna os Fornecedores localizados dentro do polígono da feição climática selecionada.
O script abaixo demonstra vários padrões úteis:
- Usa a função geometria do Arcade - generalize - para simplificar a forma do polígono selecionado para melhorar o desempenho da consulta espacial openCypher
- Mostra como você pode gerar URLs do Knowledge Studio que abrem a feição selecionada ou entidade 'gêmea' correspondente em um knowledge graph. Você também pode gerar URLs para explorar outras entidades relacionadas para exploração mais profunda.
Código exemplo: script Arcade ponta a ponta com consulta ao grafo para serviço independente do knowledge graph
// O ID do item portal do serviço Knowledge Graph (pid) e URL do portal servidor (Altere estes)
var pid = "d03d80ca35c94cadb963f845acbd0de1"
var portal_url = " https://[YOUR_ORG_PORTAL_URL].com/portal/"
var kg = KnowledgeGraphByPortalItem(Portal(portal_url), pid)
// Para simplificar o polígono para melhor desempenho estamos usando a função Generalize
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
}
Como funcionam os pop-ups Arcade com grafos
'O detalhado "como fazer"',' field 71 ':' A partir do ArcGIS Enterprise 11.3 e ArcGIS Pro 3.3 ',' field 72 ':' Expressões Arcade ',' field 73 ':' podem consultar ArcGIS Knowledge Graphs a partir de pop-ups personalizados em mapas e gráficos de ligação. Esses pop-ups podem ser configurados para camadas de feições ou camadas do knowledge graph no ArcGIS Pro , ArcGIS AllSource , ArcGIS Knowledge Studio , Map Viewer e aplicativos web map .',' field 74 ':' O pop-up usa funções gráficas Arcade para enviar informações da feição , entidade ou relacionamento selecionado para uma consulta gráfica . A consulta pode retornar entidades conectadas , detalhes dos relacionamentos , resumos calculados , correspondências espaciais ou saída formatada que aparece diretamente no pop-up .',' field 75 ':' Para ',' field 76 ':' pop-ups da camada de feições ',' field 77 ':' , normalmente corresponde-se à entidade do knowledge graph usando GUID compartilhado , ID ativo , ID instalação , ID lote ou outro atributo único . O pop-up também pode passar a geometria da feição selecionada para uma consulta espacial gráfica para encontrar entidades gráficas que intersectam , estão dentro ou se relacionam com essa área .',' field 78 ':' Para ',' field 79 ':' pop-ups da camada do knowledge graph ',' field 80 ':' , a entidade ou relacionamento selecionado já é o ponto inicial . O Arcade pode usar essa seleção para consultar contexto gráfico adicional , resumir dados conectados ou gerar uma URL do Knowledge Studio que abre a entidade relacionada para exploração mais profunda .',' field 81 ':' Padrão Arcade para Consultar ArcGIS Knowledge Graphs a partir dos Pop-ups ',' field 82 ':' A maioria dos pop-ups baseados em Arcade seguem o mesmo padrão básico : identificar o grafo , definir a feição ou entidade selecionada como entrada , executar uma consulta gráfica , formatar os resultados e retornar um dicionário pronto para o pop-up . Vamos passar por cada etapa .',' field 83 ':' Etapa 1 — Identificar o Grafo Conhecimento para Consultar ',' field 84 ':' No Arcade , “conectar”-se a um knowledge graph significa identificar o grafo que deseja consultar . Use ',' field 85 ':' KnowledgeGraphByPortalItem() ',' field 86 ':' para referenciar um grafo por item portal . Se o pop-up for construído sobre uma Camada Knowledge Graph e consultar o mesmo grafo , você pode pular esta etapa e usar ',' field 87 ':' $graph ',' field 88 ':' diretamente na consulta .',' field 89 ':' Se o grafo estiver armazenado em outro portal ArcGIS Enterprise , os usuários podem ser solicitados a entrar nesse portal quando o mapa ou gráfico abrir .',' field 90 ':' Certifique-se que o modelo dos dados do grafo — tipos de entidades , tipos de relacionamentos e propriedades — esteja alinhado com os identificadores , atributos ou geometria usados pela expressão do pop-up .',' field 91 ':' Código exemplo : referenciar o knowledge graph ',' field 92 ':' // Opção A : consultar um grafo alvo por item portal ',' field 93 ':' var portalUrl = "https://[YOUR_ORG_PORTAL_URL]/portal";',' field 94 ':' var graphItemId = "[KNOWLEDGE_GRAPH_ITEM_ID]";',' field 95 ':' var kg = KnowledgeGraphByPortalItem(Portal(portalUrl), graphItemId);',' field 96 ':' // Opção B : consultar o mesmo grafo da camada gráfica selecionada ',' field 97 ':' var kg = $graph;',' field 98 ':' Etapa 2 — Identificar a Feição , Entidade ou Geometria Que Deseja Consultar ',' field 99 ':' Em seguida , decida o que o pop-up passará na consulta gráfica : atributo da feição , geometria da feição selecionada ou entidade / relacionamento gráfico selecionado .',' field 100 ':' Para pop-ups da camada de feições , isso geralmente significa :',' field 101 ':' Escolher um identificador compartilhado , como GUID , ID ativo , ID instalação , ID lote ou outro atributo único .',' field 102 ':' Usar esse valor para encontrar a entidade correspondente ou contexto conectado no knowledge graph .',' field 103
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 a geometria da feição selecionada como entrada para uma consulta de grafo espacial que retorna entidades que intersectam, estão contidas ou relacionadas a essa forma. | · Encontre fornecedores a jusante dos fornecedores dentro de um polígono selecionado. · Agregue estatísticas das propriedades em entidades ou relacionamentos conectados |
Código de exemplo: capture a entrada selecionada
// Entrada baseada em atributo de uma feição selecionada
var selectedId = $feature.[SHARED_ID_FIELD];
var params = { id: selectedId };
// Entrada da camada de grafo de uma entidade selecionada
var selectedGuid = $feature.globalid;
Para pop-ups da camada de grafo, a entidade selecionada já é o ponto inicial, então a expressão normalmente pode usar diretamente o GUID dessa entidade.
Consultas de grafo também podem usar a geometria da feição selecionada para filtrar resultados espacialmente, como no exemplo da cadeia de suprimentos descrito acima.
// Entrada baseada em geometria de uma feição selecionada
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}
Esta etapa ancora a consulta na feição, entidade, relacionamento ou geometria que o usuário selecionou.
Passo 3 — Escreva a Lógica da Consulta do Grafo
Defina o insight que o pop-up deve retornar. Operações comuns de consulta incluem:
- Recuperar entidades vizinhas, como fornecedores, ativos, instalações, pessoas ou documentos.
- Percorrer relacionamentos multi-hop, como fornecedores a montante ou clientes a jusante.
- Filtrar por status, período de tempo, categoria, tipo de relacionamento ou relevância espacial.
- Calcular resumos como contagens, totais, classificações, pontuações de risco ou listas de categorias.
- Combinar múltiplas consultas de grafo em uma única resposta do pop-up.
O objetivo é transformar dados conectados do grafo em uma resposta concisa que o usuário possa entender rapidamente.
Código de exemplo: execute consultas de relacionamento e grafo espacial
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 }
);
Passo 4 — Formate os Resultados para o Pop‑up
Após a consulta retornar resultados, formate-os para o pop-up. A maioria das expressões:
- Constrói um dicionário com seções nomeadas ou saída formatada.
- Formata resultados como texto, listas, pequenas tabelas ou links.
- Retorna um objeto estruturado que o mecanismo de pop-up do ArcGIS pode renderizar.
É aqui que os resultados brutos do grafo se tornam contexto legível para a feição do mapa selecionada, entidade ou elemento do gráfico de links.
Código de exemplo: formate resultados do grafo para exibição
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 = "Nenhum resultado relacionado ao grafo encontrado.";
}
Passo 5 — Retorne o Dicionário Final
Finalmente, retorne o dicionário. O ArcGIS lê o objeto retornado e renderiza o texto formatado, seções, tabelas, links ou controles no pop-up.
Código de exemplo: retorne o conteúdo do pop-up
return {
type: 'text',
text: finalText
};
Formate Resultados da Consulta do Knowledge Graph do ArcGIS em Pop-ups
Expressões Arcade podem formatar resultados de consultas de grafo em várias formas amigáveis para pop-ups. Padrões comuns incluem:
- Gerar seções com listas expansíveis ou tabelas das entidades relacionadas resultantes que correspondem ao seu padrão
- Gerar tabelas das entidades resultantes e estatísticas criadas usando a consulta
- Gerar links dinâmicos para entidades (a partir da versão 11.4) ou consultas salvas (a partir da versão 12.0) no aplicativo web Knowledge Studio usando Parâmetros URL.
Veja exemplo: Arcade_Graph_Pop-ups.mp4
Exemplo Completo: Script Arcade completo de ponta a ponta
No exemplo simples (repetido acima), a consulta do grafo dentro da expressão Arcade retorna os Fornecedores localizados dentro do polígono de uma feição meteorológica selecionada. O script também usa a função geometry do Arcade - generalize' - para simplificar a forma do polígono selecionado e melhorar o desempenho da consulta espacial openCypher.
'//O ID do item portal do serviço Knowledge Graph (pid) e URL do portal servidor (Altere estes)'
'var pid = "d03d80ca35c94cadb963f845acbd0de1"'
'var portal_url = " https://[YOUR_ORG_PORTAL_URL].com/portal/"'
'var kg = KnowledgeGraphByPortalItem(Portal(portal_url), pid)'
' '
'// Para simplificar o polígono para melhor desempenho, estamos usando a função Generalize'
'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'
' }'
'Este é um exemplo de uma consulta que você poderia usar em um ','Map',' field 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!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!',' field with an independent ','Feature Service',' there for reference alongside a spatial Knowledge Graph layer or the graph might not be present in the map at all!'.replace('Map', 'Mapa').replace('Feature Service', 'Serviço de Feição').replace('Knowledge Graph', 'Knowledge Graph').replace('Arcade', 'Arcade').replace('LLMs', 'LLMs').replace('AI', 'IA').replace('URL Parameters', 'Parâmetros URL').replace('Knowledge Studio', 'Knowledge Studio').replace('openCypher', 'openCypher').replace('Generalize', 'Generalize').replace('StandardizeGuid', 'StandardizeGuid').replace('server_url', 'server_url')}}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!
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.
