Search Knowledge Graphs

Note: Sign in to access the data in this sample. username: viewer01 password: I68VGU^nMurF

Getting Started

A knowledge graph allows you work with a graph network. This network connects people, places, and things (represented by entities) with each other through relationships that define how they are associated. Both entities and relationships can have associated properties. And an entity with a spatial location can be connected with other entities that do not have a spatial location.

This sample demonstrates searching a knowledge graph executeSearchStreaming().

The sample dataset contains observations of bumble bees made at locations around the United States. Each observation was made and verified by users and is of a specific species of bumble bee.

sample-data-model

Good search terms include states abbreviations (e.g. CA, WA), countries, parks, and bumble bee descriptors (e.g. fuzzy, yellow, spotted).

Jump to how it works

For additional information on working with knowledge graph services see:

How to use this sample

1. Sign in

The data in this example is secured, as most knowledge graph data will be since the ArcGIS Knowledge Graph Server license is required. Therefore, the first step is to sign in to load the data.

In this sample sign in with the following credentials: username: viewer01 password: I68VGU^nMurF.

2. Enter search term

Enter a search term. The default search term is "bombus" (Latin name for the genus bumble bee) but you can provide any search term such as "yellow" for yellow-tailed bumble bee or "california" for all observations made in the state.

search-term

3. Specify Parameters

Specify whether to search for the term just in the properties of entities, just in the properties of relationships, or in the properties of both.

search-types

To search with no additional parameters, run the search.

Optional properties

Streaming search has the following optional properties.

  • Start index

    The record index to start the search. All records before this index will be ignored.

  • Maximum number of records

    The maximum number of records to return from the search. By default this is not specified so all results will be returned unless the number of results exceeds the maxRecordCount parameter in the serviceDefinition of the knowledge graph. If the maxRecordCount is reached, then it will return all results up to that limit.

  • Named types to search

    Limit the search to specific entity or relationship types. Any number of types can be specified. All types are searched by default.

  • IDs to search

    Limit the search to specific record ids. Any number of ids can be specified. All ids are searched by default.

  • Return search context

    If checked, the result also returns the names of the properties that matched the search term for each record, and the scores of how well each result matches the search term.

The search may take a few seconds to return results. The records with properties that match the search term are listed, with the first one selected to show it's properties. Select any returned result to see it's properties.

How it Works

The first step is to connect to a knowledge graph using fetchKnowledgeGraph. This returns the service definition and data model for the knowledge graph. You can then use the data model to populate the list of entity types and relationship types that are in the graph.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
    // set knowledge graph with url to service
    const url = "https://sampleserver7.arcgisonline.com/server/rest/services/Hosted/BumbleBees/KnowledgeGraphServer";
    const knowledgeGraph = await knowledgeGraphService.fetchKnowledgeGraph(url);
    const typeSelect = document.getElementById("streaming-search-named-types");
    const searchButton = document.getElementById('streaming-search-button');

    //use the knowledge graph data model to create the dropdowns for the named type selection
    knowledgeGraph.dataModel.entityTypes.forEach((entityType) => {
      typeSelect.innerHTML += `<calcite-combobox-item value="${entityType.name}" heading="${entityType.name}"></calcite-combobox-item>`;
    })
    knowledgeGraph.dataModel.relationshipTypes.forEach((relType) => {
      typeSelect.innerHTML += `<calcite-combobox-item value="${relType.name}" heading="${relType.name}"></calcite-combobox-item>`;
    })

Streaming search returns results in small chunks allowing the client to begin processing the data returned immediately rather than waiting for the entire result set to be returned before processing. Streaming is faster, more efficient, and will retrieve all matching records, even if the total exceeds the search limits set in the service definition. Another benefit of streaming is that the request is encoded which means that it is far smaller than a traditional HTTP GET or JSON POST body.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
    //Search the graph using the options provided.
    //only the search term and typeCategoryFilter are required as search parameters
    searchButton.addEventListener('click', async (e) => {
      //get search inputs
      const searchString = document.getElementById("streaming-search-keyword").value
      const typeFilter = document.getElementById("streaming-search-type-filter").value
      const namedTypes = document.getElementById("streaming-search-named-types").value
      const index = document.getElementById("streaming-search-start-index").value
      const limit = document.getElementById("streaming-search-limit").value
      const ids = document.getElementById("streaming-search-ids").value
      const context = document.getElementById('streaming-search-context').checked
      //construct the search object
      const searchParams = {
        searchQuery: searchString,
        typeCategoryFilter: typeFilter,
        returnSearchContext: context,
      }
      if (index) { searchParams["start"] = index };
      if (limit) { searchParams["num"] = limit };
      if (namedTypes) { searchParams["namedTypesFilter"] = typeof namedTypes == "string" ? [namedTypes] : namedTypes };
      if (ids) { searchParams["idsFilter"] = [ids] };
      //execute the search and read the result
      const searchResults = await knowledgeGraphService.executeSearchStreaming(knowledgeGraph, searchParams)
      readStream(searchResults);
    })

Each chunk returned by a streaming search is a readable stream that must be read before the results can be used. After the chunk is read it can be used in other client side processing. In this case it is used to create and display of the result.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
    // a function to read the stream returned from the streaming search
    const readStream = async (streamingQueryResult) => {
      //create the reader
      let reader = streamingQueryResult.resultRowsStream.getReader();
      //try to read the stream
      try {
        while (true) {
          //read the stream
          const { done, value } = await reader.read();
          if (done) {
            break;
          }
          createList(value)
        }
        // if there is an error in returning the stream or the stream is aborted
      } catch (err) {
        if (err.name === "AbortError") {
          console.log("Request aborted as expected");
        } else {
          throw err;
        }
      }
    };

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.