com.esri.arcgis.geodatabase
Class IQueryFilterProxy

java.lang.Object
  extended by com.esri.arcgis.interop.Dispatch
      extended by com.esri.arcgis.geodatabase.IQueryFilterProxy
All Implemented Interfaces:
IQueryFilter, Externalizable, Serializable
Direct Known Subclasses:
IQueryFilter2Proxy, ISpatialFilterProxy

public class IQueryFilterProxy
extends com.esri.arcgis.interop.Dispatch
implements IQueryFilter, Serializable

Provides access to members that filter data based on attribute values and or relationships.

Description

IQueryFilter filters data based on an attribute query. A string defining a where clause is required. An optional list of columns may be included to specify the column values to be retrieved. If no columns are specified, all values will be returned.

Remarks

Unlike the QueryDef object, QueryFilter objects are supported across all workspace types, including shapefiles and coverages.

For datasets that support it, an ORDER BY clause can be set on the attribute query by using the IQueryFilterDefinition::PostfixClause property.

When To Use

When you need to filter data based on attribute values or the relationships between attributes.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

See Also:
IQueryDef, ISpatialFilter, esriSpatialRelEnum, Serialized Form

Field Summary
 boolean noncastable
           
 
Fields inherited from class com.esri.arcgis.interop.Dispatch
DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, objRef
 
Constructor Summary
  IQueryFilterProxy()
           
  IQueryFilterProxy(Object obj)
           
protected IQueryFilterProxy(Object obj, String iid)
           
 
Method Summary
 void addField(String subField)
          Appends a single field name to the list of sub-fields.
 void addListener(String iidStr, Object theListener, Object theSource)
           
 ISpatialReference getOutputSpatialReference(String fieldName)
          The spatial reference in which to output geometry for a given field.
 String getSubFields()
          The comma delimited list of field names for the filter.
 String getWhereClause()
          The where clause for the filter.
 void removeListener(String iidStr, Object theListener)
           
 void setOutputSpatialReferenceByRef(String fieldName, ISpatialReference outputSpatialReference)
          The spatial reference in which to output geometry for a given field.
 void setSubFields(String subFields)
          The comma delimited list of field names for the filter.
 void setWhereClause(String whereClause)
          The where clause for the filter.
 
Methods inherited from class com.esri.arcgis.interop.Dispatch
bindUsingMoniker, constructVtblPosTable, convertToNative, cookieForListener, createDispatch, createObjrefMonikerDisplayName, equals, getActiveObject, getActiveObject, getDefaultProperty, getDispatchIdOfName, getLastErrorCode, getMtsObjectContext, getObjRef, getPropertyByName, getPropertyByName, getVtblPos, hashCode, initDispatch, invoke, invokeMethodByName, invokeMethodByName, invokeMethodByName, invokePropertyGetByName, invokePropertyPutByName, invokePropertyPutByRefByName, isNativeMode, isObjRef, optimizedVtblInvoke, queryInterface, readExternal, release, setNativeMode, setPropertyByName, toString, vtblInvoke, writeExternal
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

noncastable

public boolean noncastable
Constructor Detail

IQueryFilterProxy

public IQueryFilterProxy()

IQueryFilterProxy

public IQueryFilterProxy(Object obj)
                  throws IOException
Throws:
IOException

IQueryFilterProxy

protected IQueryFilterProxy(Object obj,
                            String iid)
                     throws IOException
Throws:
IOException
Method Detail

addListener

public void addListener(String iidStr,
                        Object theListener,
                        Object theSource)
                 throws IOException
Overrides:
addListener in class com.esri.arcgis.interop.Dispatch
Throws:
IOException

removeListener

public void removeListener(String iidStr,
                           Object theListener)
                    throws IOException
Overrides:
removeListener in class com.esri.arcgis.interop.Dispatch
Throws:
IOException

getSubFields

public String getSubFields()
                    throws IOException,
                           AutomationException
The comma delimited list of field names for the filter.

Description

You can use the SubFields property to improve performance when using query filters. The performance gain comes from just fetching the field values that you require rather than all the data for each row. The default value for SubFields is "*", which indicates that all field values will be returned. Setting it back to this original (default) "*" can be done either by setting it to "*" or to "".

The SubFields property should be a comma-delimited list of the columns that are required. For example, to retrieve two fields named "OBJECTID" and "NAME", the property should be set to "OBJECTID, NAME" (the space is optional).

It isn’t necessary to set the subfields when the query filter is used in a context in which no attribute values are fetched, for example, when selecting features.

Remarks

When accessing rows from a subset of data defined by a query filter, all the fields will be present, but just those specified by SubFields will be populated with values. This ensures that the field index positions for an object remain constant no matter how it was hydrated.

When editing data, always use "*" for the SubFields property.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSubFields in interface IQueryFilter
Returns:
The subFields
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setSubFields

public void setSubFields(String subFields)
                  throws IOException,
                         AutomationException
The comma delimited list of field names for the filter.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setSubFields in interface IQueryFilter
Parameters:
subFields - The subFields (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addField

public void addField(String subField)
              throws IOException,
                     AutomationException
Appends a single field name to the list of sub-fields.

Remarks

The AddField method can be used to add a field to the SubFields list before the query is executed. Adding a field will clear the default "*" value from the SubFields. Setting it back to this original "*" can be done either by setting Subfields to "*" or to "".

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
addField in interface IQueryFilter
Parameters:
subField - The subField (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getWhereClause

public String getWhereClause()
                      throws IOException,
                             AutomationException
The where clause for the filter.

Description

The WhereClause property allows you to specify an expression which will constrain the features returned from the QueryFilter. For example, you can use the WhereClause property to select all the polygons with an area greater than 1,500 square units: "AREA" > 1500.

The expression specified with the WhereClause property is a SQL query. The syntax of the query differs depending on the data source you are using, as it is in the native format of the database or data source. An application can use the ISQLSyntax interface on a Workspace to determine information about the SQL syntax used, such as the delimiting character used in qualifying table and field names and the identifier quote character.

Field names

- If you are querying data in a file geodatabase, shapefile, dBase table, coverage, INFO table, then field names are enclosed in double quotes:
"AREA"

- If you are querying data in a personal geodatabase then field names are enclosed in square brackets:
[AREA]
- If you are querying data in an ArcSDE geodatabase or an ArcIMS image service or feature service, then fields are not enclosed:
AREA
- If you are querying data in a worksheet in an Excel file (.xls file) or a text file (.txt file), fields are delimited in single quotes 'AREA' unless you are working in the Select By Attributes dialog launched from the table window, in which case square brackets [AREA] are used.

Use ISQLSyntax::GetSpecialCharacter to return the delimited identifier prefix and suffix for the data source.

Strings

Strings must always be enclosed within single quotes. For example:

"STATE_NAME" = 'California'

Personal geodatabases stored in Access are case insensitive to field values, whereas ArcSDE, File and shapefiles are case sensitive. To make a case insensitive search in other data formats, you can use a SQL function to convert all values to the same case. For file-based data sources, use either the UPPER or LOWER function.

For example, given a field value of "Florida", a WhereClause of "State_name = 'florida'" will return one USA state when run against a data in a personal geodatabase, but none with and shapefiles and ArcSDE. A WhereClause of "State_name = 'Florida'" will return one feature in all cases.

For example, the following expression will select customers whose last name is stored as either Jones or JONES:

UPPER("LAST_NAME") = 'JONES'

Other data sources have similar functions. Personal geodatabases, for example, have functions named UCASE and LCASE that perform the same function.

Use the LIKE operator (instead of the = operator) to build a partial string search. For example, this expression would select Mississippi and Missouri among the USA state names:

"STATE_NAME" LIKE 'Miss%'

Use ISQLSyntax::GetSpecialCharacter to return the delimited identifier prefix and suffix for the data source.

Wildcard Characters

A wildcard character is a special symbol that stands for one or more characters.

For any file-based data, '%' means that anything is acceptable in its place: one character, a hundred characters, or no character. Alternatively, if you want to search with a wildcard that represents one character, use '_'.

For example, this expression would select any name starting with the letters Cath, such as Cathy, Catherine, and Catherine Smith:

"NAME" LIKE 'Cath%'

But this expression would find Catherine Smith and Katherine Smith:
"OWNER_NAME" LIKE '_atherine smith'

The wildcards you use to query personal geodatabases are '*' for any number of characters and '?' for one character.

Use ISQLSyntax::GetSpecialCharacter to return the wildcard specific for the data source being queried.

NOTE: If you use a wildcard character in a string with the = operator, the character is treated as part of the string, not as a wildcard.

With a joined table, use wildcards appropriate for the side of the join that you are querying. If the query only applies to fields in the target table (the left-side table), use the target table wildcards. If the query only applies to fields in the join table (the right-side table), use the join table wildcards. If the query involves fields from both sides of the join, use the '%' and '_' wildcards.

For example, if you join a dbf file (the join table) to a personal geodatabase feature class (the target table):

1) Use * for queries that only involve personal geodatabase fields.

2) Use % for queries that only involve dbf columns.

3) Use % for queries involving columns from both sides of the table.

The NULL keyword

Null values are supported in fields for geodatabases and for date fields in shapefiles/dBASE tables and coverages/INFO tables.

The Distinct keyword

The Distinct keyword is not supported by file geodatabases. The recommended workaround is to use the IDataStatistics::UniqueValues method to return the distinct values for a field.

Querying numbers

You can query numbers using the equal (=), not equal (<>), greater than (>), less than (<), greater than or equal (>=), and less than or equal (<=) operators.

"POPULATION96" >= 5000

Querying dates

The syntax required for querying dates depends on the data type. ArcMap will automatically write the proper syntax for you when you double-click a date value in the Unique Values list. See the SQL reference mentioned above for more about querying dates.

Reference

For more information on using SQL in a query filter, see the ArcGIS web help article, SQL reference.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
getWhereClause in interface IQueryFilter
Returns:
The whereClause
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setWhereClause

public void setWhereClause(String whereClause)
                    throws IOException,
                           AutomationException
The where clause for the filter.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setWhereClause in interface IQueryFilter
Parameters:
whereClause - The whereClause (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getOutputSpatialReference

public ISpatialReference getOutputSpatialReference(String fieldName)
                                            throws IOException,
                                                   AutomationException
The spatial reference in which to output geometry for a given field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Specified by:
getOutputSpatialReference in interface IQueryFilter
Parameters:
fieldName - The fieldName (in)
Returns:
A reference to a com.esri.arcgis.geometry.ISpatialReference
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setOutputSpatialReferenceByRef

public void setOutputSpatialReferenceByRef(String fieldName,
                                           ISpatialReference outputSpatialReference)
                                    throws IOException,
                                           AutomationException
The spatial reference in which to output geometry for a given field.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Specified by:
setOutputSpatialReferenceByRef in interface IQueryFilter
Parameters:
fieldName - The fieldName (in)
outputSpatialReference - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.