Common Query Language

Common Query Language (CQL) is a formal language for representing queries to Information retrieval systems such as web indexes, bibliographic catalogs and museum collection information. The design objective is that queries be human readable and writable, and that the language be intuitive while maintaining the expressiveness of more complex languages.

Traditionally, query languages have fallen into two camps: powerful, expressive languages, not easily readable or writable by non-experts (e.g. SQL, PQF, and XQuery); or simple and intuitive languages not powerful enough to express complex concepts (e.g. CCL and Google).

CQL tries to combine simplicity and intuitiveness of expression for simple, every day queries, with the richness of more expressive languages to accommodate complex concepts when necessary.

WMS uses CQL in the request to filter the returned response. This capability provides enhanced flexibility and better user control over response results for sophisticated users of the services.

	The parameter name coverage_cql_filter is used for GetMap requests and the parameter name cql_filter is used for GetFeatureInfo requests.

CQL Filter Principle

The following examples illustrate CQL filter principles and their usage.

WFS Examples

WMS Examples

How to Combine Two Attributes in a CQL Filter

There are two approaches to combining two attributes in a CQL Filter.

Post syntax (xml)
get syntax (CQL-based)

The filter can be an arbitrarily complex expression, such as:

property = value

(property = value)AND(otherProperty > otherValue)

Sub-expressions can be put together with AND and OR to form more complex expressions.

The following table lists the possible CQL Filter parameters.

	The CQL filter parameters can be determined by running a DescribeFeatureType request. See Web Feature Service.

CQL Filter Parameters
Element	DataType	Example Value	Example Usage	Description
featureId	string	17027d713c0c3d9eaef07e80d959e347	featureId='17027d713c0c3d9eaef07e80d959e347'	A string that uniquely identifies the particular Feature to be included or excluded from returned results.
geometry	gml:GeometryPropertyType	34.068123,-96.509471,34.098737,-96.472678	BBOX(geometry,34.068123,-96.509471,34.098737,-96.472678)	A GML polygon representing the geometry of the Feature instance; the GML includes the Coordinate System of the polygon.
acquisitionDate	string	2009-05-27 01:20:43.63599	acquisitionDate>='2009-05-27 01:20:43.63599'	For source_unit="Strip", the GMT of acquisition of the image used to make the product described by the Feature; for other source_unit values, the GMT of acquisition of the oldest image contained in the product described by the Feature.
acquisitionTime	int	1753	acquisitionTime='1753'	Time of acquisition date in HHMM format
sensorType	string	Do not include
source	string	WV01	source='WV01'	The sensor used to collect the imagery used to make the product described by the Feature.
sourceUnit	string	Strip	sourceUnit='Strip'	The type of product described by the Feature.
productType	string	Panchromatic	productType='Panchromatic'	The type of product described by the Feature. Pan Sharpened Natural Color Panchromatic
CE90Accuracy	string	4.21	CE90Accuracy<=4.21	The geographic accuracy of the product described by the Feature, in Meters, as a CE90 value. CE90, Circular Error of 90%, is commonly used for quoting and validating geodetic image registration accuracy. A CE90 value is the minimum diameter of the horizontal circle that can be centered on all photoidentifiable Ground Control Points (GCPs) and also contain 90% of their respective twin counterparts acquired in an independent geodetic survey.
RMSEAccuracy	string	7.63	RMSEAccuracy<=7.63	The geographic accuracy of the product described by the Feature, in Meters, as a 2d RMS Error value. RMSE, Root Mean Squared Error, is commonly used for quoting and validating geodetic image registration accuracy. A RMSE value is a single summary statistic that describes the square-root of the mean horizontal distance between all photo-identifiable GCPs and their respective twin counterparts acquired in an independent geodetic survey.
cloudCover	float	0.5	cloudCover<=0.5	The cloud cover percentage of the image used to make the product described by the Feature; this will be 0 for products made from more than one image.
offNadirAngle	float	37.6	offNadirAngle<=37.6	The off-nadir angle of the image used to create the product described by the Feature; this will be null for products made from more than one image.
sunElevation	float	83.5	sunElevation<=83.5	The elevation angle of the sun for the image used to make the product described by the Feature; this will be null for products made from more than one image.
sunAzimuth	float	-117.3	sunAzimuth>=-117.3	The azimuth angle of the sun for the image used to make the product described by the Feature; this will be null for products made from more than one image.
groundSampleDistance	float	0.5	groundSampleDistance=0.5	The GSD of the product described by the Feature.
groundSampleDistanceUnit	string	Meter	groundSampleDistanceUnit='Meter'	The units of the field groundSampleDistance.
dataLayer	string	daily_take	dataLayer='daily_take'	Defines the layer in which the product described by the Feature exists. crisis_event (FirstLook - Natural and human caused disasters) country_coverage (Global Basemap Countries) metro (Global Basemap Cities) aerial_cells (Global Basemap Aerial Cells. U.S. and Western Europe Coverage only) aerial_markets (GBM Aerial Markets/urban areas. US and Western EU) aerial_cir_cells (Color infrared version of aerial cells) aerial_cir_markets (Color infrared version of aerial markets) monitoring (AssuredLook – monitoring of selected sites)
legacyDescription	string	AOI4_L3_WV2	legacyDescription='AOI4_L3_WV2'	A text description of the product described by the Feature.
outputMosaic	boolean	TRUE	outputMosaic=TRUE	True if the product described by the Feature consists of multiple images, as in the case of a Region Tile; "False" if the product type is Strip.
colorBandOrder	string	RGB	colorBandOrder='RGB'	Null for panchromatic data; otherwise the order in which the spectral bands occur in the product described by the Feature.
assetName	string	FINISHED	assetName='FINISHED'	The Name of the catalog that contains the Product described by the Feature.
assetType	string	PRODUCT_GEOMETRY	assetType='PRODUCT_GEOMETRY'	The Type of the catalog that contains the Product described by the Feature.
legacyId	string	10300100AE766C00	legacyId='10300100AE766C00'	If source_unit is "Strip", this is the Maxar internal identifier of the image used to make the product described by the Feature; for other source_units, this field is null.
factoryOrderNumber	string	052187237-10	factoryOrderNumber='013291395-10'	The order number that identifies the product described by this Feature within the Maxar internal systems.
perPixelX	float	4.50E-06	perPixelX<=0.0000045	The pixel size in the x direction; the unit is determined by the "crsFromPixels" value.
perPixelY	float	4.50E-06	perPixelY<=0.0000045	The pixel size in the y direction; the unit is determined by the "crsFromPixels" value.
crsFromPixels	string	EPSG:4326	crsFromPixels='EPSG:4326'	The Coordinate Reference System of the Product described by the Feature.
url	string
ageDays	int	14	ageDays<14	The age (in days) of the image from today's date.
formattedDate	string	2021-06-21	formattedDate='2021-06-21'	Ingest date without timestamp
ingestDate	string	2010-06-21 13:20:43.63599	ingestDate<='2020-06-21 13:20:43.63599'	The GMT time at which the Feature was made available in SecureWatch.
spatialAccuracy	string	1:50,000	spatialAccuracy='1:50,000'	The accuracy of the product described by the Feature, using the NMAS accuracy scales. National map accuracy standards are specifications of accuracy standards for well-defined map points on published maps that are specified by the U.S. Geological Survey and revised by the U.S. Bureau of the Budget.
earliestAcquisitionDate	string	2021-06-28 17:53:56	earliestAcquisitionDate='2021-06-28 17:53:56'	Earliest date of imagery acquisition
latestAcquisitionDate	string	2021-06-28 17:53:56	latestAcquisitionDate='2021-06-28 17:53:56'	Latest date of imagery acquisition
pixelsIngested	boolean	true	pixelsIngested=true
preciseGeometry	boolean	true	preciseGeometry=true
vendorName	string
vendorReference	string
companyName	string
acquisitionType	string
orbitDirection	string
licenseType	string
isBrowse	boolean	false	isBrowse=false	True = Browse, non-native resoultion; False = Native resolution
isMirrored	boolean	false	isMirrored=false	True = image has been mirrored, False = non-mirrored image
isMultipleWKB	boolean	false	isMultipleWKB=false	True = multiple objects, False = single object
copyright	string
beamMode	string
polarisationMode	string
polarisationChannel	string
antennaLookDirection	string
minimumIncidenceAngle	float
maximumIncidenceAngle	float
incidenceAngleVariation	float
niirs	float	5.1	niirs>=5.1	National Imagery Interpretability Rating Scale value
verticalAccuracy	float
tagsAsString	string