SQL Views

The traditional way to access database data is is to configure layers against either tables or database views. Starting with GeoServer 2.1.0, layers can also be defined as SQL Views. SQL Views allow executing a custom SQL query on each request to the layer. This avoids the need to create a database view for complex queries.

Even more usefully, SQL View queries can be parameterized via string substitution. Parameter values can be supplied in both WMS and WFS requests. Default values can be supplied for parameters, and input values can be validated by Regular Expressions to eliminate the risk of SQL injection attacks.

SQL Views are read-only, and thus cannot be updated by WFS-T transactions.

Creating a SQL View

In order to create a SQL View the administrator invokes the Create new layer page. When a database store is selected, the usual list of tables and views available for publication appears, A link Configure new SQL view... also appears:

../_images/createsqlview.png

Selecting the Configure new SQL view... link opens a new page where the SQL view query can be specified:

../_images/createsql.png

Note

The query can be any SQL statement that is valid as a subquery in a FROM clause (that is, select * from (<the sql view>) [as] vtable). This is the case for most SQL statements, but in some databases special syntax may be needed to call stored procedures. Also, all the columns returned by the SQL statement must have names. In some databases alias names are required for function calls.

When a valid SQL query has been entered, press the Refresh link in the Attributes table to get the list of the attribute columns determined from the query:

../_images/sqlview-attributes.png

GeoServer attempts to determine the geometry column type and the native SRID, but these should be verified and corrected if necessary.

Note

Having a correct SRID (spatial reference id) is essential for spatial queries to work. In many spatial databases the SRID is equal to the EPSG code for the specific spatial reference system, but this is not always the case (for instance, Oracle has a number of non-EPSG SRID codes).

If stable feature ids are desired for the view’s features, one or more columns providing a unique id for the features should be checked in the Identifier column. Always ensure these attributes generate a unique key, or filtering and WFS requests will not work correctly.

Once the query and the attribute details are defined, press Save. The usual New Layer configuration page will appear. If further changes to the view are required, the page has a link to the SQL View editor at the bottom of the Data tab:

../_images/sqlview-edit.png

Once created, the SQL view layer is used in the same way as a conventional table-backed layer, with the one limitation of being read-only.

Parameterizing SQL Views

A parametric SQL view is based on a SQL query containing named parameters. The values for the parameters can be provided dynamically in WMS and WFS requests. They can have default values specified. Input validation is supported by specifying validation regular expressions. Parameter values are only accepted if they match the regular expression defined for them. Appropriate parameter validation should always be used to avoid the risk of SQL injection attacks.

Warning

SQL View parameter substitution should be used with caution, since improperly validated parameters open the risk of SQL injection attack. Where possible, consider using safer methods such as dynamic filtering in the request, or Variable substitution in SLD.

Parameter names are delimited by % signs in the query. Here is an example of a SQL View query for a layer called popstates with two parameters, low and high:

../_images/sqlview-parametricsql.png

Each parameter needs to be defined with its name, default value, and validation expression. The Guess parameters from SQL link can be clicked to infer the query parameters automatically, or they can be entered manually. The result is a table filled with the parameter names, default values and validation expressions:

../_images/sqlview-paramdefault.png

Default values are optional, but in this case they should be specified, since the query cannot be executed without values for the parameters (because the query select gid, state_name, the_geom from pgstates where persons between and is invalid SQL). Since the SQL query requires the parameters to be positive integer numbers, the validation regular expressions should be specified to allow only numeric input (i.e. ^[\d]+$):

../_images/sqlview-paramcustom.png

Once the default values have been set the Attributes Refresh link can be clicked to parse the query and retrieve the attribute columns. The geometry and identifier details can be corrected if required. From this point the workflow is the same as for a non-parameterized query.

Using a parametric SQL View

The popstates SQL View layer can be displayed by invoking the Layer Preview. Initially all the states are displayed, since no parameter values have been supplied and so the defaults are used. The SQL view parameters are specified by adding the viewparams parameter to the WMS GetMap request. The viewparams argument is structured as a list of key:value pairs, separated by semicolons:

viewparams=p1:v1;p2:v2;...

If the values contain semicolons or commas these must be escaped with a backslash (e.g. \, and \;).

For example, to display all states having more than 20 million inhabitatants the following parameter is added to the GetMap request:

&viewparams=low:20000000
../_images/sqlview-20millions.png

To display all states having between 2 and 5 millions inhabitatants the view parameters are:

&viewparams=low:2000000;high:5000000
../_images/sqlview-2m-5m.png

Parameters can be provided for multiple layers by separating each parameter map with a comma:

&viewparams=l1p1:v1;l1p2:v2,l2p1:v1;l2p2:v2,...

The number of parameter maps must match the number of layers (featuretypes) included in the request.

Parameters and validation

The value of a SQL View parameter can be an arbitrary string of text. The only constraint is that the attribute names and types returned by the view query must never change. This makes it possible to create views containing parameters representing complex SQL fragments. For example, using the view query select * from pgstates %where% allows specifying the WHERE clause of the query dynamically. However, this would likely require an empty validation expression. which presents a serious risk of SQL injection attacks. This technique should only be used if access to the server is restricted to trusted clients.

In general, SQL parameters must be used with care. They should always include validation regular expressions that accept only the intended parameter values. Note that while validation expressions should be constructed to prevent illegal values, they do not necessarily have to ensure the values are syntactically correct, since this will be checked by the database SQL parser. For example:

  • ^[\d\.\+-eE]+$ checks that a parameter value contains valid characters for floating-point numbers (including scientific notation), but does not check that the value is actually a valid number
  • [^;']+ checks that a parameter value does not contain quotes or semicolumn. This prevents common SQL injection attacks, but otherwise does not impose much limitation on the actual value

Resources for Regular expressions

Creating proper validation regular expressions is important for security. Regular expressions are a complex topic that cannot be fully addressed here. The following are some useful resources for constructing regular expressions:

Previous: Database Connection Pooling
Next: Controlling feature ID generation in spatial databases