com.esri.arcgis.geodatabase
Class QueryFilter

java.lang.Object
  com.esri.arcgis.geodatabase.QueryFilter

All Implemented Interfaces:

IQueryFilter, IQueryFilter2, IQueryFilterDefinition, IQueryFilterDefinition2, com.esri.arcgis.interop.RemoteObjRef, IClone, IPersist, IPersistStream, IXMLSerialize, Externalizable, Serializable

public class QueryFilter
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IQueryFilter, IQueryFilter2, IQueryFilterDefinition, IQueryFilterDefinition2, IClone, IPersistStream, IXMLSerialize, Externalizable

Esri Query Filter object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:

Serialized Form

Constructor Summary

QueryFilter()
Constructs a QueryFilter using ArcGIS Engine.

QueryFilter(Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
QueryFilter theQueryFilter = (QueryFilter) obj;

Method Summary

void	addField(String subField) Appends a single field name to the list of sub-fields.
void	assign(IClone src) Assigns the properties of src to the receiver.
void	deserialize(IXMLSerializeData data) Deserializes an object from XML.
boolean	equals(Object o) Compare this object with another
IClone	esri_clone() Clones the receiver and assigns the result to *clone.
void	getClassID(GUID[] pClassID) getClassID
static String	getClsid() getClsid.
IFilterDefs	getFilterDefs() The filter definitions specified for this query filter.
ISpatialReference	getOutputSpatialReference(String fieldName) The spatial reference in which to output geometry for a given field.
String	getPostfixClause() A clause that will be appended to the SELECT statement, following the where clause.
String	getPrefixClause() A clause that will be inserted between the SELECT keyword and the SELECT COLUMN LIST.
void	getSizeMax(_ULARGE_INTEGER[] pcbSize) getSizeMax
double	getSpatialResolution() The spatial resolution in which to output geometry.
String	getSubFields() The comma delimited list of field names for the filter.
String	getWhereClause() The where clause for the filter.
int	hashCode() the hashcode for this object
void	isDirty() isDirty
boolean	isEqual(IClone other) Indicates if the receiver and other have the same properties.
boolean	isIdentical(IClone other) Indicates if the receiver and other are the same object.
void	load(IStream pstm) load
void	readExternal(ObjectInput in)
void	save(IStream pstm, int fClearDirty) save
void	serialize(IXMLSerializeData data) Serializes an object to XML.
void	setFilterDefsByRef(IFilterDefs filters) The filter definitions specified for this query filter.
void	setOutputSpatialReferenceByRef(String fieldName, ISpatialReference outputSpatialReference) The spatial reference in which to output geometry for a given field.
void	setPostfixClause(String clause) A clause that will be appended to the SELECT statement, following the where clause.
void	setPrefixClause(String clause) A clause that will be inserted between the SELECT keyword and the SELECT COLUMN LIST.
void	setSpatialResolution(double resolution) The spatial resolution in which to output geometry.
void	setSubFields(String subFields) The comma delimited list of field names for the filter.
void	setWhereClause(String whereClause) The where clause for the filter.
void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef

getJintegraDispatch, release

Constructor Detail

QueryFilter

public QueryFilter()
            throws IOException,
                   UnknownHostException

Constructs a QueryFilter using ArcGIS Engine.

Throws:

IOException - if there are interop problems

UnknownHostException - if there are interop problems

QueryFilter

public QueryFilter(Object obj)
            throws IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
QueryFilter theQueryFilter = (QueryFilter) obj;

Construct a QueryFilter using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to QueryFilter.

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems

Method Detail

getClsid

public static String getClsid()

getClsid.

equals

public boolean equals(Object o)

Compare this object with another

Overrides:

equals in class Object

hashCode

public int hashCode()

the hashcode for this object

Overrides:

hashCode in class Object

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.

getSpatialResolution

public double getSpatialResolution()
                            throws IOException,
                                   AutomationException

The spatial resolution in which to output geometry.

Description

The SpatialResolution method provides generalization of shapes returned by a filter. The generalization is performed on the server to minimize network travel. A zero value is default and will result in no generalization. The higher the value, the greater the generalization performed. The value is specified in feature units and generally should be roughly the size of one display pixel (measured in feature units).

This method is only supported on ArcGIS feature service and ArcIMS data sources. It will be ignored on all other data sources.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getSpatialResolution in interface IQueryFilter2

Returns:

The resolution

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSpatialResolution

public void setSpatialResolution(double resolution)
                          throws IOException,
                                 AutomationException

The spatial resolution in which to output geometry.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

setSpatialResolution in interface IQueryFilter2

Parameters:

resolution - The resolution (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getPostfixClause

public String getPostfixClause()
                        throws IOException,
                               AutomationException

A clause that will be appended to the SELECT statement, following the where clause. Most commonly used for clauses like ORDER BY.

Remarks

The PostfixClause property allows for a postfix clause to be added to a query filter. The PostfixClause property is a string property. It can be used to specify an ORDER BY clause for the query. Historically, this clause has not been supported due to issues with placement in the SQL generated for spatial and/or versioned queries. This property ensures proper placement of the clause in the SQL generated by the system.

Product Availability

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

Specified by:

getPostfixClause in interface IQueryFilterDefinition

Returns:

The clause

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setPostfixClause

public void setPostfixClause(String clause)
                      throws IOException,
                             AutomationException

A clause that will be appended to the SELECT statement, following the where clause. Most commonly used for clauses like ORDER BY.

Product Availability

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

Specified by:

setPostfixClause in interface IQueryFilterDefinition

Parameters:

clause - The clause (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getFilterDefs

public IFilterDefs getFilterDefs()
                          throws IOException,
                                 AutomationException

The filter definitions specified for this query filter.

Remarks

The FilterDefs property contains the set of FilterDefs objects that will be applied to the query.

Product Availability

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

Specified by:

getFilterDefs in interface IQueryFilterDefinition

Returns:

A reference to a com.esri.arcgis.geodatabase.IFilterDefs

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setFilterDefsByRef

public void setFilterDefsByRef(IFilterDefs filters)
                        throws IOException,
                               AutomationException

The filter definitions specified for this query filter.

Product Availability

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

Specified by:

setFilterDefsByRef in interface IQueryFilterDefinition

Parameters:

filters - A reference to a com.esri.arcgis.geodatabase.IFilterDefs (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getPrefixClause

public String getPrefixClause()
                       throws IOException,
                              AutomationException

A clause that will be inserted between the SELECT keyword and the SELECT COLUMN LIST. Most commonly used for clauses like DISTINCT or ALL.

Product Availability

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

Specified by:

getPrefixClause in interface IQueryFilterDefinition2

Returns:

The clause

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setPrefixClause

public void setPrefixClause(String clause)
                     throws IOException,
                            AutomationException

A clause that will be inserted between the SELECT keyword and the SELECT COLUMN LIST. Most commonly used for clauses like DISTINCT or ALL.

Product Availability

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

Specified by:

setPrefixClause in interface IQueryFilterDefinition2

Parameters:

clause - The clause (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_clone

public IClone esri_clone()
                  throws IOException,
                         AutomationException

Clones the receiver and assigns the result to *clone.

Product Availability

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

Specified by:

esri_clone in interface IClone

Returns:

A reference to a com.esri.arcgis.system.IClone

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

assign

public void assign(IClone src)
            throws IOException,
                   AutomationException

Assigns the properties of src to the receiver.

Description

Use Assign method to assign the properties of source object to receiver object. Both objects need to have the same CLSIDs. Both source and receiver objects need to be instantiated.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

assign in interface IClone

Parameters:

src - A reference to a com.esri.arcgis.system.IClone (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isEqual

public boolean isEqual(IClone other)
                throws IOException,
                       AutomationException

Indicates if the receiver and other have the same properties.

Description

IsEqual returns True if the receiver and the source have the same properties. Note, this does not imply that the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

isEqual in interface IClone

Parameters:

other - A reference to a com.esri.arcgis.system.IClone (in)

Returns:

The equal

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isIdentical

public boolean isIdentical(IClone other)
                    throws IOException,
                           AutomationException

Indicates if the receiver and other are the same object.

Description

IsIdentical returns true if the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

isIdentical in interface IClone

Parameters:

other - A reference to a com.esri.arcgis.system.IClone (in)

Returns:

The identical

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isDirty

public void isDirty()
             throws IOException,
                    AutomationException

isDirty

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

isDirty in interface IPersistStream

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

load

public void load(IStream pstm)
          throws IOException,
                 AutomationException

load

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

load in interface IPersistStream

Parameters:

pstm - A reference to a com.esri.arcgis.system.IStream (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

save

public void save(IStream pstm,
                 int fClearDirty)
          throws IOException,
                 AutomationException

save

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

save in interface IPersistStream

Parameters:

pstm - A reference to a com.esri.arcgis.system.IStream (in)

fClearDirty - The fClearDirty (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSizeMax

public void getSizeMax(_ULARGE_INTEGER[] pcbSize)
                throws IOException,
                       AutomationException

getSizeMax

Description

IPersistStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getSizeMax in interface IPersistStream

Parameters:

pcbSize - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getClassID

public void getClassID(GUID[] pClassID)
                throws IOException,
                       AutomationException

getClassID

Description

IPersist is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getClassID in interface IPersist

Parameters:

pClassID - A Structure: com.esri.arcgis.support.ms.stdole.GUID (out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

serialize

public void serialize(IXMLSerializeData data)
               throws IOException,
                      AutomationException

Serializes an object to XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

serialize in interface IXMLSerialize

Parameters:

data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

deserialize

public void deserialize(IXMLSerializeData data)
                 throws IOException,
                        AutomationException

Deserializes an object from XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

deserialize in interface IXMLSerialize

Parameters:

data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException