| This function requires Global Mapper Advanced |
The Search Vector Data tool searches for features in all loaded vector data by attribute value, name, or built-in attributes of the layer such as Feature Type or Index. When selected, the Search Vector Data dialog is displayed (seen below).
The search vector data tool can be accessed from the Search Menu Search by Attribute, Name and Description. It can also be accessed from the Search Vector Data button on the Tools Toolbar, or the
Search button on the Attribute Editor.
In addition to the search dialog, the Search Vector Data tool also displays an Attribute Editor Search Results list of all of the vector features (areas, lines, points and/or lidar) which match the specified Search Criteria. The Search Criteria can be applied to any attribute value of the loaded features, the display label field, or the description/ type field. The expression entered into the Query section updates the displayed rows in the corresponding Attribute Editor window when the Search button at the bottom is pressed.
The default search query will display all features in all layers. To change the default see General Configuration
To build a search query, type the query into the search box, or use the Query Builder attributes, operators, functions and values to build the query expression. Like other scripting syntax in Global Mapper, the attribute names, operators and functions are not case sensitive.
For a simple attribute query:
- Press the Clear Query button in the bottom right of the dialog to clear out the default query.
- Select an attribute from the Query Builder Attributes list, and double-click it or use the + button below the attribute list to add it to the query. Note the % characters surrounding the attribute name indicate it is a variable.
- Select the operator ( = , >, <, etc.)
- With the attribute still highlighted in the attribute list, press the Load Values button to populate box with a list of the values for the selected attribute.
- From the Values list, double-click or select the desired value and press the + button to add it to the query expression. Note the value will be added to the query inside quotes (' or ") if it is a text string.
- Optionally press the Validate button to test the expression.
- Press the Search button at the bottom of the dialog to perform the query. The features that match the query will display in the Attribute Editor window.
The Feature Types, Layer(s) and Feature Options sections at the top of the dialog can be used to further limit the search results.
Settings
Feature Types
In the Feature Types section of the dialog, feature types may be selected or disabled to include or exclude Areas, Lines, Points or Lidar data from searches. By default all feature types will be selected, so the result may include areas, lines, points or lidar.
Layer(s)
In the Layer(s) section, the search can be limited to specific layers, or the extent of data visible on the screen*.
All Enabled layers are visible layers that also have the option 'Allow Feature Selection/ Search from selected Layer(s)' checked in the Control Center right-click context menu. Layers that have been disabled from search and selection will appear with a red layer name in the Control Center.
Specific Layers can be used to constrain the search to particular layers. This is enabled by default when accessing the Search Vector Data from a Layer attribute list.
* The limitation on the number of features that can be listed is 5 million. To search Lidar data with more than the maximum number of features, you will have to use the 'Search Onscreen Features Only' option, and zoom in the viewer to reduce the number of features.
Feature Options
On-screen Features - Select this option to limit the results to only those features displayed on the primary 2D map.
Selected Features- Check this option to limit the search to within the current selected features. This option can be used to combine attribute search with other selection methods. To combine attribute searches with spatial queries, perform a selection using the Digitizer Advanced Selection Options (or other digitizer tool selection) and enable the Sync button. Then perform this attribute search with the Selected Features option enabled.
Validate
Press the validate button to verify the syntax of the query is correct.
Clear Query
This button will clear the query text.
Load Saved Query
This will open the Query Manager providing a list of queries previously saved in the workspace or on the machine.
Highlight a query and press OK to load a previously saved query.
Delete – This will delete the highlighted query.
Import – Use this option to load a *.gm_query file previously exported or collected from the User Data folder.
Export – Use the Export options to save a set of queries to a *.gm_query file. This can be shared with another user, or later reloaded in another workspace. All checked queries will be included in the export. Use the Check All or Clear All button to help make the proper selection for export.
Save Query
This option will save the search query to a file or to the workspace. It can be reloaded later using the Load Saved Query option.
Note: Query statements reference attribute names, and the attribute name must be exactly the same in the loaded data for the query to run properly. Use the validate button to ensure that the referenced query works with the current attribute data, or replace the attribute names contained in the %% to run an equivalent search on a different set of attribute names.
Enter Query Name – Specify a name to save the query as. This will be used to reload the query using the Load Saved Query button. To overwrite an existing query select it from the drop-down list of existing queries, otherwise type a new name.
Include all search options – Check this option to include other parts of the query dialog settings beyond just the query statement. This includes the settings under Feature Types, Layers, Feature Options, and Default Comparison mode.
Save in current workspace – Check this option to save the query only in the current workspace. This is one way to include the query if the workspace is opened on another machine. It means the query will not be available when other workspaces are loaded. When this option is not checked, queries are saved in the User Data Folder in a saved_vector_searches.gm_query file.
Query Builder
The query builder can be used to build an expression in the query box that search based on attributes of the loaded vector features. The desired attributes, functions and values must be double-clicked or added with the + button, so that the text in the query box shows a valid expression. It is also possible to type or paste directly into the query box.
Attributes
Attribute names must be contained inside of % characters in the query. Built-in named attributes, such as Feature Name and Index in Layer are contained inside of <> characters, and do not use the % to designate them. Highlight the attribute in the Attributes section of the query builder and select the + button to add the attribute to the query at the current cursor location.
Operators
The comparison operations are the following:
| Operator | Meaning | Example 1 | Example 2 |
|---|---|---|---|
| = | equals | %Attribute1%='Value' | %Attribute1% = %Attribute2% |
| >= | greater than or equal to | %Attribute1% >= 100 | %Attribute1% >= 'C' |
| <= | less than or equal to | %Attribute1%<= 100 | %Attribute1% <= 'Ba' |
| <> | not equal to (see also Built-in named attributes) | %Attribute1%<>"" | %CONTINENT% <> 'North America' |
| > | greater than | %Population% >1000 | <Feature Name> > 0 |
| < | less than | %AREA% < 100 | %Population%/%AREA% < 1000 |
| () | parenthesis (operations inside are executed first in the order of operations; they may also contain the inputs to a function) | %Attribute1% = (%Attribute2%*10) | %Density% <> (%Population%/%Area%) |
| and | logical AND (returns features where both expressions are matched) | %GROUP_AREA% < 1000 and %CONTINENT%= 'Europe' | %GDP_MD_EST% > 500 and %POP_EST% < 1000000 |
| or | logical OR (returns features where either expression is matched) | %CONTINENT%= 'Europe' or %CONTINENT%= 'Asia' | |
| not | logical Negation operator (this returns the inverse of the expression) | not(<Feature Name> like 'U*') | %CONTINENT% = 'Africa' and not ( %SUBREGION% = 'Western Africa' ) |
| like | matches a pattern (this can use the wildcard characters * and ?) | %SUBREGION% like 'South*' | %ELEVATION% like '??5' |
These operators may be added to the query with the operator buttons, or they can be typed directly into the query box.
Additional expression operators may be typed in as well, such as mathematical operators (like +,-, *, /, ^). For a more complete list of operators, see Formula Calculator.
Simple Attribute Queries
The typical syntax for a single attribute query is:
%Attribute1% = 'Value'
%Attribute1% > 0
%Attribute1% <> ''
The attribute name in this case would be Attribute1, and the first query would find all features where Attribute1 equals (has the exact text of) Value. This value is a text string, so it should be contained inside of single or double quotes. The third query would find all feature that do not contain an empty or null attribute1.
For a numeric value, the quotes around the value are not necessary. The second query would find all features where Attribute1 is greater than 0.
An empty or null value may be represented by two single or double quotes ('' or ""). A not operator combined with an attribute name would also return features with null values. For example:
%Attribute1% = ''
not %Attribute1%
Either of these queries would find all features where attribute1 is empty or null.
The %% wrapper designates a variable attribute value, which will be tested for each individual feature based on its attribute value. The <> indicates special built-in Attribute Name Values. In the context of the vector search dialog, the %% around the attribute name are not required, so the following query would also work:
Attribute1 = 'Value'
Simple Query Examples
These example expressions may be used on the default Countries data, which is loaded when pressing the Load Default Data button on the application start screen.
The query (shown to the right):
%CONTINENT% = 'Europe'
Will display the 800 area features belonging to a European country.
The query:
%POP_EST% > 1000000000
Will show the 105 area features that make up India and China, both of with have population over 1,000,000.
The queries:
<Feature Name> like 'A*'
<Feature Name> < 'B'
Either of these queries will show the 325 area features belonging to a country that starts with the letter A. Note the * character represents a wildcard of any length, and may only be used with the LIKE operator. The less than (<) operator can be used with text values, and will be based on alphabetically sorted values (i.e. anything starting with a number or the letter A would come before B in the alphabet).
Compound Queries
Compound attribute queries can be built with logical AND, and OR statements. A compound query would typically use the following syntax:
%Attribute1%='Value' and %Attribute2%='Value 2'
This would find all features that match both Value in Attribute1 and Value 2 in Attribute2.
%Attribute1%='Value' or %Attribute1%='another value'
This query would return all feature that have either value or another value in Attribute 1.
The expression is processed left to right, and the comparison operators return a binary value of 1 for true, and 0 for false. Since each operator is processed independently, the following syntax would not be processed as expected:
1 < %Attribute1% < 5
This expression would be processed the same as (3<%Attribute1%)<5. If 3 is less than the attribute value, the first part will return a 1. If it is greater than the attribute it will return a 0. In either case (0)<5 and (1)<5. This query will always return all features. To find attributes between a certain value, it is necessary to separate the expressions with an AND operator, for example:
1 < %Attribute1% and %Attribute1% < 5
The NOT operator can be used to negate an expression. For example:
%Attribute1%='Value' and not (%Attribute2%='Value 2')
This would return features that contain Value in attribute1, but do not contain Value 2 in attribute2.
Compound Query Examples
The following samples use the default Countries data, which is loaded when pressing the Load Default Data button on the application start screen.
The query:
<Feature Name> like 'A*' and %CONTINENT% = 'Europe'
This will display the 19 area features part of Aland Islands, Albania, Andorra and Austria.
The query:
%CONTINENT% = 'Oceania' or %CONTINENT% = 'Seven seas (open ocean)'
This will display the 796 areas that are part of Oceania or the Seven Seas.
The query:
%CONTINENT% = 'Asia' and not (%UNIQUE_NAM% = '')
This will return 20 area features that are part of Asia, and do not have an empty (null) value in the unique name attribute.
These queries:
%CONTINENT% <> 'Asia' and %POP_EST% > 100000000
%POP_EST% > 100000000 and not(%CONTINENT% = 'Asia')
Both will display 648 area features that are part of USA, Brazil, Mexico, Russia and Nigeria. There are countries with more than 100 million population not in Asia.
Like queries (with wildcards)
Like queries are used to perform searches on features that match a pattern, rather than necessarily an exact value. The expression can contain the ? and * wildcard characters when using the like operator.
- ? - Represents a single character wildcard
- * - Represents a wildcard
Like Query Examples
To find all features with a Name that starts with B, use the search criteria:
<Feature Name> like b*
To find all features with a name that starts with B that are 6 letters long:
<Feature Name> like b?????
To find all features where the first word starts with B and is 6 letters (and there may be additional words):
<Feature Name> like b????? *
Functions
The dropdown list of functions may also be used within a query. The query is run on each feature, and that feature is returned if the query is true (i.e. it matches a boolean value of 1).
A function is run on a number of inputs, which are listed inside of the (). So the basic syntax of a function is like this:
function(input1, input2, input3)
Each function lists inside of the parenthesis the type of values it expects as input. Those input are manually updated by typing in the query box to fully set up the function.
To see the available functions, select one from the drop down list. A summary of what the selected function does is displayed in the text box below the function list.
To use a function, select it from the list and use the + button to the right of the function list to add it to the expression.
Once the function is added to the query, the descriptors listed inside of the parenthesis need to be replaced with the appropriate input expressions.
For example the function len(string) may be used to search based on the length of an attribute value, rather than the value that it contains:
-
Select the len(string) function from the function list and press the + button to add it to the query.
- In the Query section of the dialog highlight the string word, so that the placeholder will be replaced with a valid input expression.
-
Use the Attributes list or type into the query to insert the input. In this example the query will determine the length of the <Feature Name> attribute that hold the label for each feature. So the query will read:
len(<Feature Name>)
-
Expression is interpreted as a boolean value of 0 for false and 1 for true. To make this expression meaning, the length of the feature name could be compared to a value. Type in the query box or use the operators to complete the expression
len( <Feature Name> ) >10
- Optionally press the Validate button to make sure that the basic syntax of the query is correct.
- Press the Search button to perform the search. This example will return all features where the Feature Name is more than 10 characters long.
For more information on the specific functions, see the Formula Calculator.
Function Examples
The following samples use the default Countries data, which is loaded when pressing the Load Default Data button on the application start screen. The below table displays a subset of the relevant attributes and features.
right( %NAME_LONG% , 7) = 'Islands'
This query will return all features where the last 7 letters of the name match Islands. This particular query could also be performed with an expression: %NAME_LONG% like '*Islands', but it also highlights how attribute values may be modified or subset to build the expression.
match(%ABBREV% , (left( %NAME_LONG% , 3)+'.') )
This query will return the 1508 area features where the abbreviation (ABBREV attribute) is the same as the first three letters of the NAME_LONG attribute, with a period added. So for example with the first row (Afghanistan) in the above image, the first 3 letters of NAME_LONG are Afg, then the period is added with the + used in this regular expression. So the first 3 letters of NAME_LONG, with a period added, match the value in ABBREV (Afg.).
The third row in the above image (Aland Islands) , the ABBREV attribute does not match Ala. so this row would not be returned.
find( %NAME_LONG%, '\s')=5
Default comparison Mode
Comparisons to the Compare Value can be done either textually or numerically.
Automatic- In most cases this will use mathematical operators for input that appear as numbers, and text operators for those that appear like text. In cases of ambiguity, it uses the type of the first operand.
Numeric - Numeric searches should be used with greater than or less than operations when expectation is a quantitative comparison.
For example, with a text search, the value '9 Union St' would be considered greater than the value '700 Middle Street', because it is ordered by the first character. With a numeric search, greater than and less than are based on the quantity, rather than the alphabetical order.
Text -This will perform the comparison based on an alphabetization of the values. For example 'Oceania' is less than 'Seven Seas (open ocean)' in the default countries data because O comes before S in the alphabet.
Make Text Comparisons Case Sensitive - The default mode is to perform case-insensitive queries. [The exception to this is regular expression inside of the Match(), Search(), Find() and Replace() functions, which are case sensitive by default]. Check this option to perform all text string searches in a case sensitive manner. For example, when this option is checked, 'France' would not be equal to 'france'.
To combine a spatial query and an attribute query:
- Open the attribute editor and enable the
sync.
- Use the digitizer selection or advanced selection options to perform a selection by location, or spatial relationships.
- Open the vector search tool and setup the query for the attribute search. Check Selected Features in the Feature Options section to search only currently selected features.
Attribute Editor (Search Results)
The results of the search will display in the Attribute Editor labeled (Search Results) anytime the search is performed on multiple layers.
The attribute list for a particular layer can also be accessed from the Control Center right-click menu Edit Attributes... option. When the search is on multiple layers, the attributes will be sorted alphabetically.
For more information on interacting with the Attribute Editor, see the Attribute Editor