Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF

geom

Description

The geom command adds a field, named geom, to each result. This field contains geographic data structures for polygon geometry in JSON. These geographic data structures are used to create choropleth map visualizations.

6.3.0 choropleth screenshot divergent us states.png

For more information about choropleth maps, see Mapping data in the Dashboards and Visualizations manual.

Syntax

geom [<featureCollection>] [allFeatures=<boolean>] [featureIdField=<string>] [gen=<double>] [min_x=<double>] [min_y=<double>] [max_x=<double>] [max_y=<double>]

Optional arguments

featureCollection
Syntax: <geo_lookup>
Description: Specifies the geographic lookup file that you want to use. Two geographic lookup files are included by default with Splunk software: geo_us_states and geo_countries. You can install your own geographic lookups from KMZ or KLM files. See Usage for more information.
allFeatures
Syntax: allFeatures=<bool>
Description: Specifies that the output include every geometric feature in the feature collection. When a shape has no values, any aggregate fields, such as average or count, display zero when this argument is used. Additional rows are appended for each feature that is not already present in the search results when this argument is used. See Examples.
Default: false
featureIdField
Syntax: featureIdField=<field>
Description: If the event contains the featureId in a field named something other than "featureId", use this option to specify the field name.
gen
Syntax: gen=<double>
Description: Specifies generalization, in the units of the data. For example, gen=0.1 generalizes, or reduces the size of, the geometry by running the Douglass Puiker Ramer algorithm on the polygons with a parameter of 0.1 degrees.
Default: 0.1
min_x
Syntax: min_x=<double>
Description: The X coordinate for the bottom-left corner of the bounding box for the geometric shape. The range for the coordinate is -180 to 180. See Usage for more information.
Default: -180
min_y
Syntax: min_y=<double>
Description: The Y coordinate for the bottom-left corner of the bounding box for the geometric shape. The range for the coordinate is -90 to 90.
Default: -90
max_x
Syntax: max_x=<double>
Description: The X coordinate for the upper-right corner of the bounding box for the geometric shape. The range for the coordinate -180 to 180.
Default: 180
max_y
Syntax: max_y=<double>
Description: The Y coordinate for the upper-right corner of the bounding box for the geometric shape. The range is -90 to 90.
Default: 90

Usage

Specifying a lookup

To use your own lookup file, you can define the lookup in Splunk Web or edit the transforms.conf file.

If you use a managed Splunk Cloud deployment you must use Splunk Web to define a lookup.

Define a geospatial lookup in Splunk Web

  1. To create a geospatial lookup in Splunk Web, you use the Lookups option in the Settings menu. You must add the lookup file, create a lookup definition, and can set the lookup to work automatically. See Define a geospatial lookup in Splunk Web in the Knowledge Manager Manual.

Configure a geospatial lookup in transforms.conf

  1. Edit the %SPLUNK_HOME%\etc\system\local\transforms.conf file, or create a new file named transforms.conf in the %SPLUNK_HOME%\etc\system\local directory, if the file does not already exist. See How to edit a configuration file in the Admin Manual.
  2. Specify the name of the lookup stanza in the transforms.conf file for the featureCollection argument.
  3. Set external_type=geo in the stanza. See

Configure geospatial lookups in the Knowledge Manager Manual.

Specifying no optional arguments

When no arguments are specified, the geom command looks for a field named featureCollection and a field named featureIdField in the event. These fields are present in the default output from a geoindex lookup.

Clipping the geometry

The min_x, min_y, max_x, and max_y arguments are used to clip the geometry. Use these arguments to define a bounding box for the geometric shape. You can specify the minimum rectangle corner (min_x, min_y) and the maximum rectangle corner (max_x, max_y). By specifying the coordinates, you are returning only the data within those coordinates.

Testing lookup files

You can use the inputlookup command to verify that the geometric features on the map are correct. The syntax is | inputlookup <your_lookup>.

For example, to verify that the geometric features in built-in geo_us_states lookup appear correctly on the choropleth map:

  1. Run the following search:

    | inputlookup geo_us_states

  2. On the Visualizations tab, zoom in to see the geometric features. In this example, the states in the United States.

Testing geometric features

You can create an arbitrary result to test the geometric features.

To show how the output appears with the allFeatures argument, the following search creates a simple set of fields and values.

| stats count | eval featureId="California" | eval count=10000 | geom geo_us_states allFeatures=true

  • The search uses the stats command, specifying the count field. A single result is created that has a value of zero ( 0 ) in the count field.
  • The eval command is used to add the featureId field with value of California to the result.
  • Another eval command is used to specify the value 10000 for the count field. You now have a single result with two fields, count and featureId.
  • When the geom command is added, two additional fields are added, featureCollection and geom.


The following image shows the results of the search on the Statistics tab.

This image shows the results of the search on the Statistics tab. There are four columns: count, featureCollection, featureId, and geom. The state of California is listed first because it has a count. All of the other states are listed in alphabetical order because they have a count of zero, which is the result of specifying the allFeatures argument.

The following image shows the results of the search on the Visualization tab. The image is zoomed in to show more detail.

This image shows the results of the search on the Visualization tab. The state of California is highlighted. Because the allFeatures argument is used, all of the other stats in the collection have an outline around their geometric features.

Examples

1. Use the default settings

When no arguments are provided, the geom command looks for a field named featureCollection and a field named featureId in the event. These fields are present in the default output from a geospatial lookup.

...| geom

2. Use the built-in geospatial lookup geo_us_states

This example uses the built-in geo_us_states lookup file for the featureCollection.

...| geom geo_us_states

3. Specify a field that contains the featureId

This example uses the built-in geo_us_states lookup and specifies state as the featureIdField. In most geospatial lookup files, the feature IDs are stored in a field called featureId. Use the featureIdField argument when the event contains the feature IDs in a field named something other than "featureId".

...| geom geo_us_states featureIdField="state"

4. Show all geometric features in the output

The following example specifies that the output include every geometric feature in the feature collection. If no value is present for a geometric feature, zero is the default value. Using the allFeatures argument causes the choropleth map visualization to render all of the shapes.

...| geom geo_us_states allFeatures=true

5. Use the built-in geo_countries lookup

The following example uses the built-in geo_countries lookup. This search uses the lookup command to specify shorter field names for the latitude and longitude fields. The stats command is used to count the feature IDs and renames the featureIdField field as country. The geom command generates the information for the chloropleth map using the renamed field country.

... | lookup geo_countries latitude AS lat, longitude AS long | stats count BY featureIdField AS country | geom geo_countries featureIdField="country"

6. Specify the bounding box for the geometric shape

This example uses the geom command attributes that enable you to clip the geometry by specifying a bounding box.

... | geom geo_us_states featureIdField="state" gen=0.1 min_x=-130.5 min_y=37.6 max_x=-130.1 max_y=37.7

See also

Mapping data in the Dashboards and Visualizations manual.

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has about using the geom command.

PREVIOUS
gentimes
  NEXT
geomfilter

This documentation applies to the following versions of Splunk® Enterprise: 6.6.0, 6.6.1, 6.6.2, 6.6.3


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters