ArcGIS Pro 3.4 API Reference Guide
ArcGIS.Core.Data.Knowledge Namespace / KnowledgeGraph Class / SubmitQuery Method
The query filter to submit
Example

In This Topic
    SubmitQuery Method
    In This Topic
    Performs an openCypher query on the knowledge graph using the given KnowledgeGraphQueryFilter. This method must be called on the MCT. Use QueuedTask.Run.
    Syntax

    Parameters

    queryFilter
    The query filter to submit

    Return Value

    Exceptions
    ExceptionDescription
    This method or property must be called within the lambda passed to QueuedTask.Run.
    Remarks
    Queries are based on the openCypher query language. Addins should call ArcGIS.Core.Data.Realtime.RealtimeCursorBase.WaitForRowsAsync on the returned KnowledgeGraphCursor instance after submitting a search to wait for rows to be returned. Addins can submit null for the query filter (or KnowledgeGraphQueryFilter.QueryText). This will result in the KnowledgeGraphQueryFilter.Default query filter being executed.
    Example
    Submit a Graph Query
    //On the QueuedTask...
    //and assuming you have established a connection to a knowledge graph
    //...
    //Construct an openCypher query - return the first 10 entities (whatever
    //they are...)
    var query = "MATCH (n) RETURN n LIMIT 10";//default limit is 100 if not specified
    //other examples...
    //query = "MATCH (a:Person) RETURN [a.name, a.age] ORDER BY a.age DESC LIMIT 50";
    //query = "MATCH (b:Person) RETURN { Xperson: { Xname: b.name, Xage: b.age } } ORDER BY b.name DESC";
    //query = "MATCH p = (c:Person)-[:HasCar]-() RETURN p ORDER BY c.name DESC";
    
    //Create a query filter
    //Note: OutputSpatialReference is currently ignored
    var kg_qf = new KnowledgeGraphQueryFilter()
    {
      QueryText = query
    };
    //Optionally - u can choose to include provenance in the results
    //(_if_ the KG has provenance - otherwise the query will fail)
    if (includeProvenanceIfPresent)
    {
      //see "Get Whether KG Supports Provenance" snippet
      if (KnowledgeGraphSupportsProvenance(kg))
      {
        //Only include if the KG has provenance
        kg_qf.ProvenanceBehavior =
          KnowledgeGraphProvenanceBehavior.Include;//default is exclude
      }
    }
    //submit the query - returns a KnowledgeGraphCursor
    using (var kg_rc = kg.SubmitQuery(kg_qf))
    {
      //wait for rows to be returned from the server
      //note the "await"...
      while (await kg_rc.WaitForRowsAsync())
      {
        //Rows have been retrieved - process this "batch"...
        while (kg_rc.MoveNext())
        {
          //Get the current KnowledgeGraphRow
          using (var graph_row = kg_rc.Current)
          {
            //Graph row is an array, process all returned values...
            var val_count = (int)graph_row.GetCount();
            for (int i = 0; i < val_count; i++)
            {
              var retval = graph_row[i];
              //Process row value (note: recursive)
              //See "Process a KnowledgeGraphRow Value" snippet
              ProcessKnowledgeGraphRowValue(retval);
            }
          }
        }
      }//WaitForRowsAsync
    }//SubmitQuery
    Convert an Open Cypher Query Result to a Selection
    QueuedTask.Run(async () =>
    {
      //Given an open-cypher qry against an entity or relationship type
      var qry = @"MATCH (p:PhoneNumber) RETURN p LIMIT 10";
    
      //create a KG query filter
      var kg_qry_filter = new KnowledgeGraphQueryFilter()
      {
        QueryText = qry
      };
    
      //save a list of the ids
      var oids = new List<long>();
      using (var kgRowCursor = kg.SubmitQuery(kg_qry_filter))
      {
        //wait for rows to be returned asynchronously from the server
        while (await kgRowCursor.WaitForRowsAsync())
        {
          //get the rows using "standard" move next
          while (kgRowCursor.MoveNext())
          {
            //current row is accessible via ".Current" prop of the cursor
            using (var graphRow = kgRowCursor.Current)
            {
              var cell_phone = graphRow[0] as KnowledgeGraphEntityValue;
              //note: some user-managed graphs do not have objectids
              oids.Add(cell_phone.GetObjectID());
            }
          }
        }
      }
      //create a query filter using the oids
      if (oids.Count > 0)
      {
        //select them on the layer
        var qf = new QueryFilter()
        {
          ObjectIDs = oids //apply the oids to the ObjectIds property
        };
        //select the child feature layer or standalone table representing
        //the given entity or relate type whose records are to be selected
        var phone_number_fl = kg_layer.GetLayersAsFlattenedList()
            .OfType<FeatureLayer>().First(l => l.Name == "PhoneNumber");
    
        //perform the selection
        phone_number_fl.Select(qf);
      }
    });
    
    Call WaitForRowsAsync With Cancellation
    //On the QueuedTask...
    //and assuming you have established a connection to a knowledge graph
    //...
    //submit query or search to return a KnowledgeGraphCursor
    //using (var kg_rc = kg.SubmitQuery(kg_qf)) {
    //using (var kg_rc = kg.SubmitSearch(kg_sf)) {
    //...
    //wait for rows to be returned from the server
    //"auto-cancel" after 20 seconds
    var cancel = new CancellationTokenSource(new TimeSpan(0, 0, 20));
    //catch TaskCanceledException
    try
    {
      while (await kg_rc.WaitForRowsAsync(cancel.Token))
      {
        //check for row events
        while (kg_rc.MoveNext())
        {
          using (var graph_row = kg_rc.Current)
          {
            //Graph row is an array, process all returned values...
            var val_count = (int)graph_row.GetCount();
            for (int i = 0; i < val_count; i++)
            {
              var retval = graph_row[i];
              //Process row value (note: recursive)
              //See "Process a KnowledgeGraphRow Value" snippet
              ProcessKnowledgeGraphRowValue(retval);
            }
          }
        }
      }
    }
    //Timeout expired
    catch (TaskCanceledException tce)
    {
      //Handle cancellation as needed
    }
    cancel.Dispose();
    Requirements

    Target Platforms: Windows 11, Windows 10

    ArcGIS Pro version: 3.2 or higher.
    See Also