User Tools

Site Tools


wdb:manuals:wdb_call_interface

Table of Contents

WDB Call Interface User Manual

Abstract

WDB is a data storage solution for weather and water data based on the PostgreSQL object-relational database system. The system utilizes PostGIS for GIS (Geographic Information Systems) support and handles regular grids (e.g., forecast fields) and point (e.g., observation) data.

This is the User's Manual for WDB Call Interface.

Introduction

The WDB Call Interface (WCI) is the official API used for retrieving data from the WDB system.

About this Manual

This manual is intended for system designers, application developers and programmers. It describes in technical terms how weather data can be retrieved from the WDB system through the WCI. It is assumed that the reader has some familiarity with databases and weather data.

For a more elaborate description of the vision and system architecture of the WDB system, see the WDB Developer's Manual.

Intended Usage

WCI is intended to be used for retrieving weather data (e.g., temperature, air pressure, etc.) for a geographic point or area, given an altitude interval and a time or time interval. It is possible to retrieve individual data values or huge quantities of data using a single API.

Outline

This document is structured as follows:

  • Key Concepts: introduction to the concepts and terms used in the documentation
  • Using the WCI: an introduction to how the WCI is used
  • Function Reference: reference documentation for each of the WCI functions
  • Data Types Reference: reference documentation for the WCI data types
  • Examples: Example programs for WCI
  • FAQ: Frequently asked questions
  • Known bugs and limitations

Key Concepts

This section provides an overview of the WCI, including some important definitions and explanations.

Overview

WCI is an API designed to retrieve weather data from the WDB system. The WCI API resides on the database server.

All function calls on WCI are executed as SQL statements. The SQL statements can be executed through a dedicated SQL client application, such as psql, pgadmin3, DbVisualizer, or by an application program through a database API such as JDBC, ODBC, libpqxx, etc. The WCI is thus not linked into the application program itself, but is a component of the database.

A data item in WDB could be an observation, a forecast, an analysis, etc. Each item consists of a value and a number of dimensions that describe the value.

A dimension could be a description of the data item (e.g., temperature), its geographic position, its altitude (or depth), the time the data item was created, the origin of the data item, etc.

In order to access the data items in WDB, the user should have an understanding of the dimensions as they are the entry point into the database. When data is retrieved from the database, a set of search criteria is given for each of the WCI dimensions. If the search criteria for a dimension is not specified (i.e., all NULLs), it is assumed the user wants to retrieve all data items, regardless of their dimension description. Please do not attempt this unless the database you are querying is extremely small.

In the context of WCI search criteria, NULL is always interpreted to mean “ALL”.

The last parameter of a WCI function call that is intended to return data is always reserved for specifying the data type to be returned (this is because most functions are overloaded to return many different forms of data. By convention, this parameter is usually given as a NULL cast to the relevant data type; for example:

NULL::wci.browsereferencetime

The dimensions are described in the following sections.

Data Provider

The Data Provider identifies the source of the data; literally, the entity that provides the data. Where multiple sources could be identified as the source of the data, the entity that can be identified closest to the creation of the data item at the time of loading is usually used.

A data provider can be a software process (e.g., Hirlam), a meteorological or climate station, an aircraft, or a person. A data provider is identified by a DataProviderName. DataProviderNames are used to search for the data. For convenience, Data Providers may be collected into groups; e.g., the DataProviderName “Hirlam” might be used to search for any of the various Hirlam processes: “Hirlam 4”, “Hirlam 8”, etc.

When searching for data, the user may specify a single DataProviderName, a list of DataProviderNames (specified using an ARRAY constructor), or NULL. NULL indicates that the user wants all data items, regardless of the data source.

DataProviderNames exist within a data provider namespace. A namespace can be defined by the WDB administrator, in order to permit the user or an application to retrieve data in an accustomed language or code set. The default namespace of WDB is the DataProviderNameSpaceId 0, and is always based on English language names and international standard codes. The data provider namespace being used in a querying session can be defined by the user when starting up the session.

To retrieve all of the DataProviderNames (excluding data provider groups) that are currently stored in the database for the currently specified namespace, the following wci.browse function call could be used:

SELECT * FROM wci.browse( NULL::wci.browsedataprovider );

To retrieve all of the DataProviderNames (including data provider groups) that the database currently has the capacity to store and display in the currently specified namespace, the following wci.info function call could be used:

SELECT * FROM wci.getDataProvider( NULL );

Place (Geographic Location)

The place (geographic location) of a data item is the position of the item on the earth in a 2D space. In WDB, the geographic location is by default specified using longitude and latitude in a WGS84 coordinate system (though this can be changed when the database is set up; consult your system administrator). The geographic dimension is specified using a geometry object and can be either a point or a polygon.

In addition to using geometry objects to retrieve data, the user can also use a PlaceName - a pre-specified name that defines a geometry object in the database - to specify location.

As for DataProviderName, PlaceNames exist within a place namespace that can be defined by the WDB administrator. The default namespace of WDB is the PlaceNameSpaceId 0; defined in international english. As for the data provider namespace, the place namespace can be defined by the user when starting up the session.

To retrieve the full list of the PlaceNames for the data values currently being stored in the database, use the following wci.browse function call:

SELECT * FROM wci.browse( NULL::wci.browseplace );

At the same time as the user specifies a location to retrieve data from, it is also possible to specify an interpolation option for location calculations. These permit the user a great deal of flexibility in searching. Currently, interpolations such as “exact”, “nearest” (retrieve the data value closest to the specified place), and “bilinear” (retrieve the closest data values and perform a bilinear interpolation of those values) are implemented.

The form of place specification then becomes one of the two following:

'Oslo'
'nearest Oslo'
'POINT(61 9)'
'bilinear POINT(61 9)'

Specifying NULL for the place definition of a query is logically equivalent to asking for all of the data items in the database, irrespective of their location.

To retrieve all of the place names that are currently registered in the database, the following WCI function call can be used:

SELECT * FROM wci.getPlaceDefinition( NULL );

Reference Time

The reference time of a data item is the moment when the data item is referenced from. For forecast data, this would typically be the reference time of the data values the forecast is based upon; for observation data, it would typically be the time when the observation data was recorded.

When searching for data, the user specifies the reference time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the reference time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser.

To retrieve a list of the reference times currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browsereferencetime );

In addition to time points, it is also possible for the user to specify time periods using a variety of keywords. The keywords are: exact (default), before, after, inside, and contains. And interval can be specified using two timestamps and separating them with the keyword TO, or a timestamp and a duration separated by the keyword FOR. As examples, consider:

exact 2009-03-31T11:20:00+00

Denotes the specific time point of 11:20 UTC, on the 31st of March, 2009. The keyword “exact” is actually redundant, as this is the default interpretation of a timestamp in WCI.

before 2009-03-31T11:20:00+00

Denotes that the user wants to return all data for the time period prior to the time point of 11:20 UTC, on the 31st of March, 2009.

after 2009-03-31T11:20:00+00

Denotes that the user wants to return all data for the time period after the time point of 11:20 UTC, on the 31st of March, 2009.

inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later.

inside 2009-03-31T11:20:00+00 FOR 2 months

Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later.

Valid Time

The valid time of a data item is the time period for which the data item is valid. The valid time is always stored in the database as a time interval.

When searching for data, the user specifies the valid time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the valid time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser.

As usual, the list of valid times stored in the database can be retrieved using the wci.browse functionality.

SELECT * FROM wci.browse( NULL::wci.browsevalidtime );

Time is specified in the same way for time periods as for time points. Examples of how the qualifiers should be interpreted are given below:

exact 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The exact keyword returns only time periods that match precisely with the time period specified.

before 2009-03-31T11:20:00+00

The before keyword returns only time periods that end before the specified time point. In other words, the time period from 2009-03-29 to 2009-03-30 would be returned by the query but the time period from 2009-03-29 to 2009-04-01 would not.

after 2009-03-31T11:20:00+00

The after keyword returns only time periods that start after the specified time point.

inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The inside keyword for time periods is true if the time period both starts and ends within the designated time (the time point specified inclusive). It does not return time periods that merely overlap (i.e., where only the start time or the end time are within the given time period).

contains 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The contains keyword returns all the data with valid times beginning prior to the specified time and ending after the specified time. Semantics are inclusive, so a valid time that matches exactly would be returned as a row by this query.

Value Parameter

Each data value can be described using a “value parameter”. The value parameter is a name that describes the physics or code table basis of the parameter value. The value parameter concept in WCI is broadly similar to the concept of meteorological parameter used in, e.g., GRIB files.

The user searches the database for a specific parameter in the database using the ValueParameterName. ValueParameterNames are specified within a parameter namespace. As with the other namespaces, the ParameterNameSpaceId 0 is reserved for the default WDB namespace, and is based on international english. Additional namespaces can be defined by the administrator of the database.

To retrieve a list of the value parameters currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browsevalueparameter );

To list all of the value parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used:

SELECT * FROM wci.getValueParameter( NULL );

Level

The Level dimension is normally used to designate the altitude or depth of the data value. Level is designated using a level interval (height from and to) and a level parameter (e.g., height above sea level, pressure). The level definition can be prefixed with a level interpolation option that permits the user a large degree of flexibility in expressing searches. Levels are specified using a level specification in string form that is parsed by the WCI.

The level designation in the WCI queries is a string. The form of the level designation when querying the database is as follows:

interpolation levelFrom TO levelTo leveparametername

The interpolations available are exact, below, above, inside, and any. The default interpolation is exact (specifying the interpolation is optional). One may also omit the TO levelTo construction if the level being specified is a point.

Specifying any for the level interpolation is logically equivalent to specifying a NULL for the level; i.e., it retrieves all data items regardless of their level (height).

The level parameter is specified using a LevelParameterName. LevelParameterNames are specified within the parameter namespace. Consequently, it is not possible to mix usage of ValueParameterNames and LevelParameterNames from different namespaces without defining a new parameter namespace. The default WDB ParameterNameSpaceId is 0 and is based on international english.

Examples of level designations are given below:

exact 2 height
above 0 height above mean sea level distance
inside 300 TO 500 isobaric surface pressure

To retrieve a full list of the levels and level parameters currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browselevelparameter );

To list all of the level parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used:

SELECT * FROM wci.getLevelParameter( NULL );

Data Version

There can be several different versions of the same data value that is valid for the same time, position, etc. This can happen with probability forecast calculations or when a data value is edited (in which case the new value may often be inserted with a higher data version). A data version is always a positive whole number.

The user may specify one or several data versions as search criteria in WCI, as well as NULL. NULL indicates that the user wants all versions of the data items specified. In addition, the user may specify the data version as a negative number; e.g., -1. Specifying -1 retrieves the maximum data version in the database (i.e., the most recent version of the data item), -2 retrieves the second most recent, and so on.

There is no wci.browse functionality to list all of the data versions of the data in the database.

Using the WCI

This section gives an overview on how to use the WCI to retrieve data values from WDB.

Outline

The following list provides a brief overview of the actions that the user takes in order to retrieve data from WCI.

  • Create a connection to the database
  • Initialize WCI
  • Read data from WDB using WCI functions (one or more times)
  • Release WCI
  • Close database connection

Open a connection

To enable communication with WCI, the user must open a connection to the database. How this is done depends very much on the application or API that is being used (consult the documentation of the program or API for information).

Using libpq,

connection_ = PQconnectdb("dbname=wdb user=myuser host=localhost");

The connection must be open and valid as long as commands are being sent and data retrieved from the database. It is worth noting that connections are a resource; the database will have limits on how many connections can be open at the same time. This is particularly important for massively multi-user applications (e.g., web applications). In such cases, the database connections must be managed with some care. There is also an amount overhead involved with setting up a connection, so it will always be more efficient to connect once and perform multiple database operations, than to connect repeatedly for each operation.

Initialize WCI

Before WCI may be used by the user, it must be initialized.

SELECT wci.begin('myuser'::name, 0::integer, 0::integer, 0::integer);

The username is used to identify the user with WCI (this is used in setting up internal WCI variables). The three following numbers are the namespace codes for data provider namespace, place name space, and parameter name space. The wci.begin can also be called without setting these three variables, in which case they are set to the default (usually 0, 0, 0) by the system.

The username of the wci user can be a different identity than the one the user connected with (always assuming, of course, that your user has appropriate rights). This allows, for instance, for a single system to act as a multiplexing front-end to retrieve data available from several distinct users.

Name spaces are used to identify what set of names should be used for searching the database. While the user is in a namespace, only the data defined in that namespace is visible to the user. If the user should wish, for some reason, to combine data from different namespaces within an application, it will be necessary to call wci.begin repeatedly; once for each time the application needs to change its namespace.

Read from the WCI

As soon as the user has initialized WCI using wci.begin, the database is ready for retrieval of data. Data is retrieved using the wci.read function, and data is searched for by setting the appropriate dimensions in that call.

Reading Point Data from WCI

The wci.read function is overloaded to permit the user to read either point data or binary data (entire grids) from the database. The last parameter in the wci.read function allows the user to specify the return type of the query. To return point data values, the user specifies wci.returnFloat.

SELECT *
FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name
				'POLYGON((10 60,11 60,11 61,10 61,10 60))',  -- Location
				'inside 1980-01-01 12:00:00Z TO 1980-01-01 18:00:00Z', -- Reference time
				NULL, -- Valid Time
				ARRAY['air temperature'],  -- Value Parameter
				'2 height',  -- Level
				ARRAY[-1], -- Data version
				NULL::wci.returnfloat -- Return type
			  )

The above query returns Hirlam data for a specific region (given by the place geometry), whose referencetime is on or between 12:00 to 18:00 on January 1, 1980; the query will return data for any valid times, for any air temperature. It will return data at 2 metre above ground, but only the latest version of such data. Values will be returned as point data.

The data provider, place definition, value parameter and level parameter must all be defined within the namespaces given in the wci.begin call that preceded the wci.read call. In this particular case, the place definition is a geometry definition, but it would also have been possible to use a placename. Consider, for example, the following query:

SELECT *
FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name
				'oslo',  -- Location
				'1980-01-01 12:00:00Z', -- Reference time
				'inside 1980-01-02 12:00:00 TO 1980-01-12 12:00:00', -- Valid Time
				ARRAY['%precipitation%'],  -- Value Parameter
				NULL,  -- Level
				NULL, -- Data version
				NULL::wci.returnfloat -- Return type
			  )

The above call returns all precipitation parameters valid for the 10 days following the given referencetime measured at the nearest point to oslo. Oslo, in this case, is a place name usually defined as a geographical point within the database. Prefixing the place name is the interpolation that we wish to use when retrieving points; we could also have used any of the alternatives defined in the reference manual below. Note the use of SQL wildcard characters in the value parameter; although these slow down queries (since wildcard searching is not as efficient as a straight comparison), it is possible to use the wci.read call in this way. Note also that names can be written in upper or lower case; the wci.read function call is not case-sensitive.

Return values

The return value from this call is one row for each value. This means that if you have chosen an interpolation type that will return several values for each grid, you will get many rows for each grid.

The actual data value is given in the column “value”. In some cases this may have a NULL value. This means that the there exists a data field for your query, and the point(s) you requested is inside the data's grid, but that grid point has explicitly gotten a “not defined” value.

Reading Grid Data from WCI

Reading grid data from the database is a two-step process. First the user retrieves the Grid ID with wci.read function (with wci.returnGId), and then the grid itself can be retrieved using the wci.fetch function call.

SELECT *
FROM wci.read ( ARRAY['hirlam norway'],    -- Data provider name
				'hirlam 10km grid',          -- Location description
				'1980-01-01 12:00:00Z',    -- Reference time
				NULL,                      -- Valid Time (returns all forecasts)
				ARRAY['air temperature'],  -- Value Parameter
				'2 height',  -- Level
				ARRAY[-1],                 -- Data version
				NULL::wci.returngid        -- Return type
			  )

The above query returns the list of grids available for Hirlam data, defined on the hirlam 10km grid (i.e., if there were data on 20km or 4km grids, these would not be returned), whose referencetime is 12:00 on January 1, 1980. The query will return all grid references to air temperature forecasts for the above configuration.

Grid IDs are essentially 8-byte integers, that are then passed to the wci.fetch command, as given below:

SELECT *
FROM wci.fetch ( 7411403,          -- Grid ID (bigint)
				 NULL::wci.grid    -- Return Type
				)

The above call returns a single row, containing a binary string containing the actual grid data. It also includes additional information detailing the configuration of the grid. For details about the wci.fetch call, see the function reference.

Return values

The return value from this call is one row for each grid. The number given in the “value” column may be used as input argument for a wci.fetch call.

Release WCI

Once the user has finished retrieving data using WCI, it is a good idea to close down WCI.

SELECT wci.end();

This is not strictly necessary, but allows the system to graciously deallocate resources and reset any settings that may have been changed by WCI.

Close Connection

Closes down the connection to the database, freeing up the resources on the database to be used by other applications.

Using libpq,

PQfinish(connection_);

Function Reference

The following sections provide a list of the functions available for usage through the WDB Call Interface.

wci.addCodeLevelParameter

The function wci.addCodeLevelParameter allows an administrator to add new Level Parameters representing code tables to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addcodelevelparameter
(
	parameterName			text,
	parameterReference 		text
)

Parameters

Parameter Description
parameterName The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code.
parameterReference Reference information for the code table.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'hybrid level' code parameter from WMO:

SELECT wci.addcodelevelparameter ( 'hybrid level', 'WMO Code Table 3, WMO publication no. 306 - Manual on Code' );

See Also

  • wci.addmeasurelevelparameter
  • wci.getcodelevelparameter
  • wci.getlevelparameter
  • wci.getmeasurelevelparameter

wci.addCodeValueParameter

The function wci.addCodeValueParameter allows an administrator to add new Value Parameters representing code tables to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addcodevalueparameter
(
	parameterName			text,
	parameterReference 		text
)

Parameters

Parameter Description
parameterName The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code.
parameterReference Reference information for the code table.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'yr weather symbol' code parameter from www.yr.no:

SELECT wci.addcodevalueparameter ( 'yr weather symbol', 'http://www.yr.no' );

See Also

  • wci.addparameterfunctiontype
  • wci.getcodevalueparameter
  • wci.getvalueparameter
  • wci.getparameterfunctiontype

wci.addDataProvider

The function wci.addDataProvider allows an administrator to add a new Data Provider to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddataprovider
(
	dataProviderName		text,
	dataProviderType 		text,
	domainDelivery			text,
	dataProviderComment		text
)

Parameters

Parameter Description
dataProviderName The canonical data provider name to be used (i.e., the data provider name set in the default name space. Ideally, this should be a universally unique name or code.
dataProviderType The type of the data provider. Currently, this may be one of the following: * Aeroplane * Computer System * Data Provider Group * Named Observation Site * Person * Ship * WCI User
domainDelivery The domain of the data delivered by the data provider. A precise domain definition helps the database to optimize the queries. The options are: * Any * Grid * Point
dataprovidercomment Supplementary information about the dataprovider.


Expected Result

The DataProviderId (key reference number).

Example

An example setting up the data provider “michael” who provides point data:

SELECT wci.adddataprovider ( 'michael', 'Person', 'Point', 'Editor of point forecasts' );

Adding a new model to the database:

SELECT wci.adddataprovider( 'longyear', 'Computer System', 'Grid', 'Model generated from longyearbyen' );

See Also

  • wci.adddataprovidertogroup
  • wci.addwciuser
  • wci.getdataprovider
  • wci.getdataprovidername
  • wci.setdataprovidername

wci.addDataProviderToGroup

The function wci.addDataProviderToGroup allows an administrator to add a specified data provider to a data provider group in WDB.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddataprovidertogroup
(
	dataProviderName		text,
	dataProviderGroup		text
)

Parameters

Parameter Description
dataProviderName The data provider name to be added to the specified group.
dataProviderGroup The data provider group that you want to add this data provider name to.


Expected Result

The DataProviderId (key reference number) of the assigned data provider.

Example

An example setting the data provider “michael” into group 'metno':

SELECT wci.adddataprovidertogroup ( 'michael', 'metno' );

See Also

  • wci.adddataprovider
  • wci.addwciuser
  • wci.getdataprovider
  • wci.getdataprovidername
  • wci.setdataprovidername

wci.addDimensionlessValueParameter

The function wci.addDimensionlessValueParameter allows an administrator to add new Value Parameters without a physical dimension to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddimensionlessvalueparameter
(
	parameterName			text,
	parameterDescription	text
)

Parameters

Parameter Description
parameterName The canonical parameter name to be used for the measure table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or measure.
parameterDescription A description of the value parameter.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'land cover' value parameter from WMO:

SELECT wci.adddimensionlessvalueparameter ( 'land cover', 'Proportion of grid cell covered by land (WMO)' );

See Also

  • wci.getvalueparameter

wci.addFunctionValueParameter

The function wci.addFunctionValueParameter allows an administrator to add new function value parameters to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addfunctionvalueparameter
(
	parameterUsage			text,
	parameterUnit			text,
	parameterFunction		text,
	parameterQuantity		text
)

Parameters

Parameter Description
parameterUsage The usage dimension of the value parameter.
parameterUnit The SI unit of the value parameter. The unit is used to determine the physical dimension of the function value parameter.
parameterFunction The function of the value parameter.
parameterQuantity The quantity type of the value parameter; either scalar or vector.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'mean wind waves duration' value parameter to the database:

SELECT wci.addfunctionvalueparameter ( 'wind waves', 's', 'mean', 'scalar' );

See Also

  • wci.getvalueparameter

wci.addLevelParameterUsage

The function wci.addLevelParameterUsage allows an administrator to add new Level Parameter usages to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addlevelparameterusage
(
	levelParameterUsage		text,
	levelDescription		text
)

Parameters

Parameter Description
levelParameterUsage A usage dimension for a level parameter.
levelDescription A description of the usage dimensions.


Expected Result

None.

Example

An example adding the 'height above ground' level usage to the database:

SELECT wci.addlevelparameterusage ( 'height above ground',
			'Denotes the height level of the value-' );

See Also

  • wci.getlevelparameterusage

wci.addMeasure

The function wci.addMeasure allows an administrator to add new measures (e.g., physical dimensions) to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasure
(
	measure 				character varying,
	distancepower 			integer,
	masspower 				integer,
	timepower 				integer,
	luminositypower 		integer,
	electriccurrentpower 	integer,
	temperaturepower 		integer,
	substanceamountpower 	integer,
	anglepower 				integer
)

Parameters

Parameter Description
measure The measure being described.
distancepower The distance dimension of the measure. Use 0 to denote none.
masspower The mass dimension of the measure. Use 0 to denote none.
timepower The time dimension of the measure. Use 0 to denote none.
luminositypower The luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpower The electric current dimension of the measure. Use 0 to denote none.
temperaturepower The temperature dimension of the measure. Use 0 to denote none.
substancepower The substance dimension of the measure. Use 0 to denote none.
anglepower The angular dimension of the measure. Use 0 to denote none.


Expected Result

None.

Example

An example adding 'acceleration' measure to the database:

SELECT wci.addmeasure ( 'acceleration', 1, 0, -2, 0, 0, 0, 0, 0 );

See Also

  • wci.getmeasure

wci.addMeasureLevelParameter

The function wci.addMeasureLevelParameter allows an administrator to add new level parameters based on measures to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasurelevelparameter
(
	parameterUsage			text,
	parameterUnit			text
)

Parameters

Parameter Description
parameterUsage The usage dimension of the level parameter.
parameterUnit The SI unit of the level parameter. The unit is used to determine the physical dimension of the measure value parameter.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'isobaric surface pressure' level parameter to the database:

SELECT wci.addmeasurelevelparameter ( 'isobaric surface', 'Pa' );

See Also

  • wci.getlevelparameter

wci.addMeasureValueParameter

The function wci.addMeasureValueParameter allows an administrator to add new value parameters based on measures to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasurevalueparameter
(
	parameterUsage			text,
	parameterUnit			text,
	parameterQuantity		text
)

Parameters

Parameter Description
parameterUsage The usage dimension of the value parameter.
parameterUnit The SI unit of the value parameter. The unit is used to determine the physical dimension of the measure value parameter.
parameterQuantity The quantity type of the value parameter.


Expected Result

The ParameterId (key reference number).

Example

An example adding the 'air temperature' value parameter to the database:

SELECT wci.addmeasurevalueparameter ( 'air', 'K', 'scalar' );

See Also

  • wci.addmeasure
  • wci.getmeasurevalueparameter

wci.addParameterFunctionType

The function wci.addParameterFunctionType allows an administrator to add new function types to be used with value parameters to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addparameterfunctiontype
(
	parameterFunctionType			text,
	parameterFunctionDescription	text
)

Parameters

Parameter Description
parameterFunctionType The name of the function type being defined for value parameters.
parameterFunctionDescription A description of the parameter function.


Expected Result

None.

Example

An example adding the 'max' function type to the database:

SELECT wci.addparameterfunctiontype ( 'max',
	'Maximum value for the period specified by the valid time interval' );

See Also

  • wci.getfunctionvalueparameter

wci.addPlacePoint

The function wci.addPlacePoint allows an administrator to add a new place definition for a point to the WDB system.

Prerequisites

  • The user must have write privileges on the database.

Syntax

wci.addplacepoint
(
	placeName				text,
	placeGeometry 			text
)

Parameters

Parameter Description
placeName The name (in the defined namespace) of the Point to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
placeGeometry The point geometry to be inserted into the place definition tables.


Expected Result

The PlaceId (key reference number).

Example

An example setting up the place point “karasjok”:

SELECT wci.addplacepoint ( 'karasjok', geomfromtext('POINT( 25.51 69.47 )') );

Adding this point to the database while logged into a place name space other than zero, will add a point with the place name of 'karasjok' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

  • wci.addplacepolygon
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.addPlacePolygon

The function wci.addPlacePolygon allows an administrator to add a new place definition for a polygon to the WDB system.

Prerequisites

  • The user must have write privileges on the database.

Syntax

wci.addplacepolygon
(
	placeName				text,
	placeGeometry 			text
)

Parameters

Parameter Description
placeName The name (in the defined namespace) of the Polygon to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
placeGeometry The point geometry to be inserted into the place definition tables.


Expected Result

The PlaceId (key reference number).

Example

An example setting up a polygon for “square at nowhere”:

SELECT wci.addplaceplygon ( 'square at nowhere',
                            geomfromtext('POLYGON(() 10.0 61.3, 10.1 61.3, 10.1 61.4, 10.0 61.4, 10.0 61.3 ))') );

Adding this polygon to the database while logged into a place name space other than zero, will add a point with the place name of 'square at nowhere' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.addPlacerRegularGrid

The function wci.addPlaceRegularGrid allows an administrator to add a new place definition for a regular grid to the WDB system.

Prerequisites

  • The user must have write privileges on the database.

Syntax

wci.addplaceregulargrid
(
	placeName	 	text,
	numX	 		int,
	numY	 		int,
	incX	 		float,
	incY	 		float,
	startX		 	float,
	startY		 	float,
	projection		text
)

Parameters

Parameter Description
placeName The name (in the defined namespace) of the grid to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
numX The number of points along the X axis of the grid.
numY The number of points along the Y axis of the grid.
incX The distance between any two points on the X axis of the grid. The unit of measure is given by the projection.
incY The distance between any two points on the Y axis of the grid. The unit of measure is given by the projection.
startX The origin X point (lower left corner) of the grid in the specified projection.
startY The origin Y point (lower left corner) of the grid in the specified projection.
projection The original projection of the grid, which also corresponds to the form it is stored as in the database..


Expected Result

The PlaceId (key reference number).

Example

An example setting up the hirlam 10km grid:

SELECT wci.addplaceregulargrid ( 'hirlam 10km grid', 248, 400, 0.100, 0.100, 5.75, -13.25, '+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs' );

Adding this grid to the database while logged into a place name space other than zero, will add a grid with the place name of 'hirlam 10km grid' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

  • wci.addplacepoint
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.addSrid

The function wci.addSrid allows an administrator to add a new SRID definition to WDB.

Prerequisites

  • The user must have write privileges on the database.

Syntax

wci.addsrid
(
	name				text,
	projection			text
)

Parameters

Parameter Description
name A descriptive name for the projection.
projection The Proj.4 definition of the projection. To avoid duplicates, the Proj.4 definition should avoid unnecessary spacing and be ended with +no_defs. It is advised to manually check the spatial_ref_sys table (using wci.getSrid) before adding new entries.


Expected Result

The SRID (spatial reference id).

Example

An example setting up the SRID of the Hirlam 10 grid (a rotated, longitude/latitude projection:

SELECT wci.addsrid ( 'Hirlam 10 SRID',
	'+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs');

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.addUnit

The function wci.addUnit allows an administrator to add a new unit to WDB.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addunit
(
	unitname					character varying,
	unittype					character varying,
	measure						character varying,
	description					character varying,
	siunitconversioncoefficient	double,
	siunitconversionterm		double
)

Parameters

Parameter Description
unitName The UCUM designation of the unit.
unitType The type of the unit. Permitted types are: 'SI Unit', 'Base Unit', and 'Conventional Unit'. Most units should be defined as the latter.
measure The associated measure of the unit.
description A description of the unit. For most units, this will simply be the unabbreviated (i.e., full) form of the unit name.
siunitconversioncoefficient The coefficient to multiply the value with in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term
siunitconversionterm The term to add to the value in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term


Expected Result

None.

Example

An example adding the degree Fahrenheit to the database:

SELECT wci.addunit( '[degF]', 'Conventional Unit', 'temperature', 'degree Fahrenheit', 0.555556, 459.67 );

An example adding the Kelvin to the database:

SELECT wci.addunit( 'K', 'SI Unit', 'temperature', 'Kelvin', 1, 0 );

See Also

  • wci.addmeasure

wci.addValueParameterUsage

The function wci.addValueParameterUsage allows an administrator to add new Value Parameter usages to the WDB system.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addvalueparameterusage
(
	valueParameterUsage		text,
	valueDescription		text
)

Parameters

Parameter Description
valueParameterUsage A usage dimension for a value parameter.
valueDescription A description of the usage dimension.


Expected Result

None.

Example

An example adding the 'mean sea level' value usage to the database:

SELECT wci.addvalueparameterusage ( 'mean sea level',
			'Value reduced to sea level assuming an isothermal layer at the measuring point's temperature.' );

See Also

  • wci.getvalueparameterusage

wci.addWciUser

The function wci.addWciuser allows an administrator to add a WCI user to the database as a data provider in WDB.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addwciuser
(
	dataProviderName		text
)

Parameters

Parameter Description
dataProviderName The data provider name to be added to the database as a WCI user.


Expected Result

The DataProviderId (key reference number) of the inserted data provider.

Example

An example adding the wci user “michael” as a new data provider:

SELECT wci.addwciuser( 'michael' );

See Also

  • wci.adddataprovider
  • wci.adddataprovidertogroup
  • wci.getdataprovider
  • wci.getdataprovidername
  • wci.setdataprovidername

wci.begin

The function wci.begin initializes the WDB Call Interface for a specified user.

Prerequisites

  • The user must have been set up as a WDB user (i.e., have access to one of the wdb user groups

Syntax

wci.begin
(
	user                    name,
	dataproviderNameSpaceId integer,
	placeNameSpaceId        integer,
	parameterNameSpaceId    integer
)
wci.begin (
	user                    name
)

Parameters

Parameter Description
user The userid to initialize the connection with
dataprovidernamespaceid The namespace to be used for dataprovider names in the session
placenamespaceid The namespace to be used for place names in the session
parameternamespaceid The namespace to be used for parameter names in the session


Expected Result

No return expected.

Example

An example setting up the user “michael” with the data provider and parameter name spaces associated with the code 1, while retaining use of the default place names:

SELECT wci.begin ( 'michael', 1, 0, 1 );

Note that the default namespaces can be defined by the WDB administrator. Consequently, the user may frequently want to just install using this namespace, which would be done with the following wci.begin call:

SELECT wci.begin ( 'michael' );

See Also

  • wci.end

wci.browse

The wci.browse function is utilized to browse the meteorological, hydrological and oceanographic data in the database. Essentially, it can be used to retrieve summary data about what data values exist in the database. The function takes as input the same search parameters as the wci.read call, but returns summarized rather than detailed data about the values in the database. Using wci.browse will usually be significantly faster than performing a similar wci.read call followed by aggregation.

The function is overloaded, and exists in many different versions, depending on the return type required.

Prerequisites

  • The user must have access to group role wdb_read
  • The user must have called wci.begin

Syntax

wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browsedataprovider
)
wci.browse
(
	returnType     wci.browsedataprovider
)
wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browseplace
)
wci.browse
(
	returnType     wci.browseplace
)
wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browsereferencetime
)
wci.browse
(
	returnType     wci.browsereferencetime
)
wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browsevalidtime
)
wci.browse
(
	returnType     wci.browsevalidtime
)
wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browsevalueparameter
)
wci.browse
(
	returnType     wci.browsevalueparameter
)
wci.browse
(
	dataProviders  ARRAY[text],
	place          text,
	referenceTime  text,
	validtime      text,
	parameters     ARRAY[text],
	level          text,
	dataVersions   ARRAY[integer],
	returnType     wci.browselevelparameter
)
wci.browse
(
	returnType     wci.browselevelparameter
)

Parameters

All the wci.browse input parameters, except the returnType, are precisely the same as the input paramaters to a wci.read call (see Section Parameters). Calling a function with only the “returnType” parameter specified is basically equivalent to calling the wci.browse function with all NULLs (indicating that all data is required). Be aware that trying to retrieve aggregates about all the data in a huge database can take a while.

The returnType specifies which of the six different types of summarized metadata the user wants to retrieve.

Expected Result

Depending on the returnType specified:

  • wci.browsedataprovider This returns a list of the data providers that exist in the database for the parameter definitions given in the wci.browse call and the utilized namespace. For each dataprovider, the number of data records and the earliest and latest referencetimes that exist for that data value is also listed.
  • wci.browseplace This returns a list of the place definitions that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each place definition, the number of data records in the database are listed.
  • wci.browsereferencetime This returns a list of the referencetimes that exist in the database for the parameter definitions given by the wci.browse call. For each referencetime, the number of data records in the database are listed.
  • wci.browsevalidtime This returns a list of the validtimes that exist in the database for the parameter definitions given by the wci.browse call. For each validtime, the number of data records in the database are listed.
  • wci.browsevalueparameter This returns a list of the value parameters that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each valueparameter, the number of data records in the database are listed.
  • wci.browselevelparameter This returns a list of the level parameters that exist in the database for the parameter definitions given by the wci.browse call and the utilized namespace. For each level parameter, the number of data records in the database are listed.

Example

The following browse query could be used to retrieve the data provider names of all data providers in the database.

SELECT * FROM wci.browse ( NULL::wci.browsedataprovider );

The user might then utilize a result from this query to ask a follow-up determining the reference times of a specific data provider.

SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ],
						   NULL, NULL, NULL, NULL, NULL, NULL,
					       NULL::wci.browsereferencetime );

The results from this query (a list of referencetimes), can then be used to drill down further into the data mass of the database. The following example retrieves the list of parameters for the given data provider and reference time.

SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ], NULL,
						   'exact 1980-03-15 12:00:00+00',
						   NULL, NULL, NULL, NULL,
					       NULL::wci.browsevalueparameter );

See Also

  • wci.read

wci.configuration

The wci.configuration function returns all configuration information (i.e., the complete list of all versions installed) for the WDB database.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.configuration
(
)

Parameters

None.

Expected Result

Configuration information.

Attribute Description
name The name of the software package.
softwareversion The version of the software.
packageversion The version of the package; this is a sequential number independent of the software version.
description A description of the software package.
installtime The time when this version of WDB was installed.


Example

An example to extract the configuration of the database:

SELECT wci.configuration ( );

See Also

  • wci.version

wci.end

The function wci.end unsets any settings and frees up resources that may have been initialized by wci.begin.

Prerequisites

None.

Syntax

wci.end
(
)

Parameters

None.

Expected Result

No return expected.

Example

The wci.end function is just a simple functional call:

SELECT wci.end ( );

See Also

  • wci.begin

wci.fetch

wci.fetch is the function used to retrieve binary data values from the database. The function takes a binary object ID returned by a wci.read call and returns a row containing the binary data (as bytea data) as well as additional relevant information required for the manipulation of the binary data.

The returned binary data should be interpreted as 4-byte floats. Some of the data may have the value not-a-number. This means that that particular point does not have any defined value.

Prerequisites

  • The user must have a valid object ID that references a grid
  • The user must have access to group role wdb_read
  • The user must have called wci.begin

Syntax

wci.fetch
(
          objectid       bigint,
          returnType     wci.grid
)

Parameters

Parameter Description
objectid The object ID of the binary object to be returned, as given by a wci.read call
returnType What type of data the user wants returned


Expected Result

Currently, the function always returns a:

  • wci.grid

Examples

The following query returns the grid referenced as 11702:

SELECT *
FROM wci.fetch ( 11702,
				 NULL::wci.grid -- Return type
               )

The result is a single row containing the binary data of the grid itself (as a bytea), in addition to the number of points along the x and y axis of the grid, the distance between grid increments, the starting positions of the x and y points in the original projection, and the PROJ.4 string defining the original projection of the grid.

See Also

  • wci.read
  • wci.write

wci.getCodeLevelParameter

The function wci.getCodeLevelParameter returns information about the specified level parameter of the code type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getcodelevelparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the level parameter in the namespace.

Table�4.23.�wci.getCodeLevelParameter return row

Attribute Description
levelparameterid The internal parameter ID used in WDB.
levelcodeparametername The canonical name of the level parameter.
codeparameterreference The reference information for the level code.
parameternamespaceid The parameter name space ID of the query.
levelparametername The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical level parameter name.


Example

An example to get information about code “hybrid level”:

SELECT wci.getcodelevelparameter ( 'hybrid level' );

To retrieve information about all code level parameters starting with “hybrid”:

SELECT wci.getcodelevelparameter ( 'hybrid%' );

See Also

  • wci.addcodelevelparameter

wci.getCodeValueParameter

The function wci.getCodeValueParameter returns information about the specified value parameter of the code type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getcodevalueparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the value parameter in the namespace.

Attribute Description
valueparameterid The internal parameter ID used in WDB.
valuecodeparametername The canonical name of the value parameter.
codeparameterreference The reference information for the value code.
parameternamespaceid The parameter name space ID of the query.
valueparametername The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.


Example

An example to get information about code “ice presence”:

SELECT wci.getcodevalueparameter ( 'ice presence' );

To retrieve information about all code value parameters starting with “ice”:

SELECT wci.getcodevalueparameter ( 'ice%' );

See Also

  • wci.addcodevalueparameter

wci.getDataProvider

The function wci.getDataProvider returns information about the specified data provider to a user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getdataprovider
(
	dataProviderName		text
)

Parameters

Parameter Description
dataProviderName The data provider name to be added to be returned. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the Data Provider in the namespace.

Attribute Description
dataproviderid The internal data provider ID used in WDB.
dataprovidertype The type classification of the data provider in WDB.
spatialdomaindelivery The spatial domain of data delivered by this data provider; either point data, gridded data, or both.
dataprovidernamespaceid The currently selected data provider name space.
dataprovidername The data provider name of the data provider in this namespace.
dataprovidernameleftset An internal WDB code used for grouping.
dataprovidernamerightset An internal WDB code used for grouping.
dataproviderstoretime The store time of this data provider; i.e., when it was inserted into the database.
dataprovidercomment Additional description or comment about the data provider.


Example

An example to get information about data provider “michael”:

SELECT wci.getdataprovider ( 'michael' );

To retrieve information about all data providers starting with “mich”:

SELECT wci.getdataprovider ( 'mich%' );

See Also

  • wci.adddataprovider
  • wci.adddataprovider2group
  • wci.addwciuser
  • wci.getdataprovidername
  • wci.setdataprovidername

wci.getDataProviderName

The function wci.getDataProviderName lists the data provider names in the namespace that match the search criteria.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getdataprovidername
(
	dataprovidername		text
)

Parameters

Parameter Description
dataProviderName The data provider name for which information is requested. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of data provider names.

Attribute Description
dataproviderid The internal data provider ID used in WDB.
dataprovidernamespaceid The currently selected data provider name space.
dataprovidername The data provider name of the data provider in this namespace.


Example

An example to list the data provider matching the name “michael”:

SELECT wci.getdataprovidername ( 'michael' );

List all data providers starting on “mich” in the name space:

SELECT wci.getdataprovidername ( 'mich%' );

See Also

  • wci.adddataprovider
  • wci.adddataprovider2group
  • wci.addwciuser
  • wci.getdataprovider
  • wci.setdataprovidername

wci.getDimensionlessValueParameter

The function wci.getDimensionlessValueParameter returns information about the specified value parameter of the dimensionless type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getdimensionlessvalueparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the value parameter in the namespace.

Attribute Description
valueparameterid The internal parameter ID used in WDB.
valuedimensionlessparametername The canonical name of the value parameter.
valueparameterdescription A description of the value parameter.
valueunitname The unit of the value parameter.
parameternamespaceid The parameter name space ID of the query.
valueparametername The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.


Example

An example to get information about the parameter “land albedo”:

SELECT wci.getdimensionlessvalueparameter ( 'land albedo' );

To retrieve information about all code value parameters starting with “land”:

SELECT wci.getdimensionlessvalueparameter ( 'land%' );

See Also

  • wci.adddimensionlessvalueparameter

wci.getFunctionValueParameter

The function wci.getFunctionValueParameter returns information about the specified value parameter of the function type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getfunctionvalueparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the value parameter in the namespace.

Attribute Description
valueparameterid The internal parameter ID used in WDB.
parameterfunctiontype The parameter function.
valueparameterusage The value parameter usage.
parameterquantitytype The quantity type of the value parameter.
measure The measure of the value parameter.
valueunitname The unit name used for the value parameter.
parameternamespaceid The parameter name space ID of the query.
valueparametername The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.


Example

An example to get information about the parameter “peak wave duration”:

SELECT wci.getfunctionvalueparameter ( 'peak wave duration' );

To retrieve information about all value parameters starting with “peak”:

SELECT wci.getfunctionvalueparameter ( 'peak%' );

See Also

  • wci.addfunctionvalueparameter

wci.getLevelParameter

The function wci.getLevelParameter returns information about the specified level parameter of the function type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getlevelparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the level parameters in the namespace.

Attribute Description
levelparameterid The internal parameter ID used in WDB.
parameternamespaceid The parameter name space ID of the query.
levelparametername The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.
levelunitname The unit of the level parameter.


Example

An example to get information about the level parameter “hybrid level”:

SELECT wci.getlevelparameter ( 'hybrid level' );

To retrieve information about all level parameters with “hybrid”:

SELECT wci.getlevelparameter ( '%hybrid%' );

See Also

  • wci.addcodelevelparameter
  • wci.addmeasurelevelparameter

wci.getlevelparameterusage

The function wci.getlevelparameterusage returns information about the specified level parameter usage to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getlevelparameterusage
(
	usage		text
)

Parameters

Parameter Description
usage The name of the parameter usage to be returned. NULL returns all parameter usages. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the level parameter usages.

Attribute Description
levelparameterusage The level parameter usage descriptor.
levelparameterusagedescription A description of the level parameter usage.


Example

An example to get information about the level usage “sea surface”:

SELECT wci.getlevelparameterusage ( 'sea surface' );

To retrieve information about all level usages with “sea”:

SELECT wci.getlevelparameterusage ( '%sea%' );

See Also

  • wci.addlevelparameterusage

wci.getMeasure

The function wci.getMeasure returns information about the specified measure to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getmeasure
(
	measure		text
)

Parameters

Parameter Description
measure The name of the measure to be returned. NULL returns all measures. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the measure.

Attribute Description
measure The measure being described.
distancepower The distance dimension of the measure. Use 0 to denote none.
masspower The mass dimension of the measure. Use 0 to denote none.
timepower The time dimension of the measure. Use 0 to denote none.
luminositypower The luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpower The electric current dimension of the measure. Use 0 to denote none.
temperaturepower The temperature dimension of the measure. Use 0 to denote none.
substancepower The substance dimension of the measure. Use 0 to denote none.
anglepower The angular dimension of the measure. Use 0 to denote none.


Example

An example to get information about the measure “distance”:

SELECT wci.getmeasure ( 'distance' );

See Also

  • wci.addmeasure

wci.getMeasureLevelParameter

The function wci.getmeasurelevelParameter returns information about the specified level parameter of the function type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getmeasurelevelparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the level parameters in the namespace.

Attribute Description
levelparameterid The internal parameter ID used in WDB.
levelparameterusage The usage of the level parameter.
measure The measure of the level parameter.
levelunitname The unit of the level parameter.
parameternamespaceid The parameter name space ID of the query.
levelparametername The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.


Example

An example to get information about the level parameter “sea surface pressure”:

SELECT wci.getmeasurelevelparameter ( 'sea surface pressure' );

To retrieve information about all level parameters with “sea”:

SELECT wci.getmeasurelevelparameter ( '%sea%' );

See Also

  • wci.addmeasurelevelparameter

wci.getMeasureValueParameter

The function wci.getmeasurevalueParameter returns information about the specified value parameter of the function type to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getmeasurevalueparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the value parameters in the namespace.

Attribute Description
valueparameterid The internal parameter ID used in WDB.
valueparameterusage The usage of the value parameter.
parameterquantitytype The quantity type of the value parameter.
measure The measure of the value parameter.
valueunitname The unit of the value parameter.
parameternamespaceid The parameter name space ID of the query.
valueparametername The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.


Example

An example to get information about the value parameter “air temperature”:

SELECT wci.getmeasurevalueparameter ( 'air temperature' );

To retrieve information about all temperature parameters:

SELECT wci.getmeasurevalueparameter ( '%temperature%' );

See Also

  • wci.addmeasurevalueparameter

wci.getParameterFunctionType

The function wci.getparameterfunctiontype returns information about the specified parameterfunctiontype to the user.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getparameterfunctiontype
(
	type		text
)

Parameters

Parameter Description
type The name of the parameterfunctiontype to be returned. NULL returns all types. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

A row of data describing the parameterfunctiontype.

Attribute Description
parameterfunctiontype The parameterfunctiontype being described.
parameterfunctiondescription A description of the parameter function type.


Example

An example to get information about the parameterfunctiontype “accumulated”:

SELECT wci.getparameterfunctiontype ( 'accumulated' );

See Also

  • wci.addparameterfunctiontype

wci.getPlaceDefinition

The function wci.getPlaceDefinition lists the place definitions defined in the database that match the search criteria and are available in the namespace.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getplacedefinition
(
	placename		text
)

Parameters

Parameter Description
placename The placename that you require information for. NULL returns all place definitions in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of place definitions.

Attribute Description
placeid The internal place ID used in WDB.
placegeometrytype The place geometry of the place definition. Currently points and grids are supported
placegeometry The geometry of the place definition in the default SRID. Note that for regular grids, only a polygon of the four corner points is stored in this field.
placeindeterminatecode The indeterminate code for the place definition.
placenamespaceid The name space of the query.
placename The place name of the place definition.
originalsrid The original SRID of the place definition. This is particularly important to keep track of for grids.
placestoretime The storetime of the place definition.


Example

An example to list the place definitions matching the name “oslo”:

SELECT wci.getplacedefinition ( 'oslo' );

List all place definitions starting on “os” in the name space:

SELECT wci.getplacedefinition ( 'os%' );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.getPlaceName

The function wci.getPlaceName lists the place names defined in the database that match the search criteria and are available in the namespace.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getplacename
(
	placename		text
)
wci.getplacename
(
	numberX 			int,
	numberY 			int,
	incrementX 			float,
	incrementY 			float,
	startX	 			float,
	startY	 			float,
	projdefinition	 	text
)

Parameters

Parameter Description
placename The placename that you require information for. NULL returns all place names in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.
numberx The number of points along the x axis in the regular grid.
numbery The number of points along the y axis in the regular grid.
incrementx The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters.
incrementy The increment distance on the y axis.
startx The starting point of the grid on the x axis of the original Proj.4 projection.
starty The starting point of the grid on the y axis of the original Proj.4 projection.
projdefinition The original PROJ.4 projection of the place definition.


Expected Result

The list of place grids.

Attribute Description
placeid The internal place ID used in WDB.
placenamespaceid The name space of the query.
placename The place name of the place definition.


Example

An example to list the placenames matching “osl”:

SELECT wci.getplacename ( 'osl%' );

List the place grid matching a set of attributes:

SELECT wci.getplacename ( 248,
		            400,
			    0.5,
			    0.5,
			    35.6,
			    -25.4,
			    "+proj=longlat +a=6367470.0 +towgs84=0,0,0 +no_defs" );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacepoint
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.getPlacePoint

The function wci.getPlacePoint lists all the place points defined in the database that match the search criteria and are available in the namespace.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getplacepoint
(
	placename		text
)

Parameters

Parameter Description
placename The placename that you require information for. NULL returns all place points in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of place points.

Attribute Description
placeid The internal place ID used in WDB.
placegeometrytype The place geometry of the place point. Currently points and grids are supported
placegeometry The geometry of the place point.
placeindeterminatecode The indeterminate code for the place point.
placenamespaceid The name space of the query.
placename The place name of the place point.
originalsrid The original SRID of the place point.
placestoretime The storetime of the place point.


Example

An example to list the place points matching the name “oslo”:

SELECT wci.getplacepoint ( 'oslo' );

List all place points starting on “os” in the name space:

SELECT wci.getplacepoint ( 'os%' );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplaceregulargrid
  • wci.getsrid
  • wci.setplacename

wci.getPlaceRegularGrid

The function wci.getPlaceRegularGrid lists the place grids defined in the database that match the search criteria and are available in the namespace.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getplaceregulargrid
(
	placename		text
)

Parameters

Parameter Description
placename The placename that you require information for. NULL returns all place grids in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of place grids.

Attribute Description
placeid The internal place ID used in WDB.
placegeometrytype The place geometry of the place definition. Currently points and grids are supported
placegeometry The geometry of the place definition.
placeindeterminatecode The indeterminate code for the place definition.
placenamespaceid The name space of the query.
placename The place name of the place definition.
numberx The number of points along the x axis in the regular grid.
numbery The number of points along the y axis in the regular grid.
incrementx The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters.
incrementy The increment distance on the y axis.
startx The starting point of the grid on the x axis of the original Proj.4 projection.
starty The starting point of the grid on the y axis of the original Proj.4 projection.
originalsrid The original SRID of the place definition. This is particularly important to keep track of for grids.
projdefinition The original PROJ.4 projection of the place definition.
placestoretime The storage time of the place definition.


Example

An example to list the place grid matching the name “hirlam 10 grid”:

SELECT wci.getplaceregulargrid ( 'hirlam 10 grid' );

List all place grid starting on “hirlam” in the name space:

SELECT wci.getplaceregulargrid ( 'hirlam%' );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getsrid
  • wci.setplacename

wci.getSrid

The function wci.getSrid lists all the spatial reference ID's defined in the database that match the search criteria and are available in the namespace.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getsrid
(
	projstr			text
)

Parameters

Parameter Description
projstr The Proj.4 string that matches the SRID you want to retrieve. NULL returns all SRIDs in the spatial reference system table. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of SRIDs.

Attribute Description
srid The spatial reference ID. An integer value that uniquely identifies the Spatial Referencing System (SRS) within the database.
auth_name The name of the standard or standards body that is being cited for this reference system. For example, “EPSG” would be a valid auth_name.
auth_srid he ID of the Spatial Reference System as defined by the Authority cited in the auth_name. For EPSG data, for example, this is the EPSD id number.
srtext The Well-Known Text representation of the Spatial Reference System. WDB ignores this column and always inserts NULL.
proj4text This is the Proj.4 coordinate definition string for a particular SRID.


Example

An example to list the SRID's with longitude/latitude projections:

SELECT wci.getsrid ( '%+proj=longlat%' );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplaceregulargrid
  • wci.addsrid
  • wci.setplacename

wci.getunit

The function wci.getunit lists all the units defined in the database that match the search criteria.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getunit
(
	unit		text
)

Parameters

Parameter Description
unit The UCUM designation of the unit. NULL returns all units in the database. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of units.

Attribute Description
unitname The name (context-sensitive UCUM designation) of the unit.
unittype The type of the unit.
measure The measure of the unit, if any.
description A description of the unit.
siunitconversioncoefficient The coefficient to multiply the value with to get the SI unit (if any). The formula is (value * coefficient) + term
siunitconversionterm The term to add to the value to get the SI unit (if any). The formula is (value * coefficient) + term


Example

An example to list all units with pressure (Pascal):

SELECT wci.getunit ( '%Pa%' );

See Also

  • wci.addunit

wci.getValueParameter

The function wci.getValueParameter lists all the value parameters defined in the database that match the search criteria.

Prerequisites

  • The user must have read access to the database.

Syntax

wci.getvalueparameter
(
	parameter		text
)

Parameters

Parameter Description
parameter The name of the value parameter in the name space. NULL returns all value parameters in the name space. PostgreSQL wild cards (used in LIKE statements) may be used.


Expected Result

The list of valueparameters.

Attribute Description
valueparameterid The internal parameter ID of the value parameter.
parameternamespaceid The currently selected parameter name space.
valueparametername The name of the valueparameter in the name space.
valueparameterunit The unit of measure of the value parameter.


Example

An example to list all value parameters based on temperature:

SELECT wci.getvalueparameter ( '%temperature%' );

See Also

  • wci.addvalueparameter

wci.read

wci.read is the function that fetches MHO data from the database, and as such is the core of the WDB Call Interface. The function takes the user's search parameters as input and returns data as either individual point, or as a reference to a complete data grid (a Grid ID - shortened as GId).

The function is overloaded, and exists in two almost identical versions, depending on the return type required.

Prerequisites

  • The user must have access to group role wdb_read
  • The user must have called wci.begin

Syntax

wci.read
(
          dataProviders  ARRAY[text],
          place          text,
          referenceTime  text,
          validtime      text,
          parameters     ARRAY[text],
          level          text,
          dataVersions   ARRAY[integer],
          returnType     wci.returnfloat
)
wci.read
(
          dataProviders  ARRAY[text],
          place          text,
          referenceTime  text,
          validtime      text,
          parameters     ARRAY[text],
          level          text,
          dataVersions   ARRAY[integer],
          returnType     wci.returngid
)

Parameters

Parameter Description
dataProviders List of data providers for the MHO data to be retrieved
place A text string containing either a geometry describing the geographic locations that the user is interested in retrieving data for (formatted using well-known-text) or a placename. The string may optionally be prefixed with a place interpolation description.
referenceTime When the MHO data was created
validtime What time is the MHO data valid for
parameters What MHO-parameters the user is interested in retrieving
level What level (altitude/depth) the data is located at
dataVersion What version of the data should be returned
returnType What type of data the user wants returned


Geospatial definitions are defined using well-known-text. Only POINTs and POLYGONs are currently supported.

Expected Result

Depending on the returnType specified:

  • wci.returnfloat
  • wci.returngid

Examples

The following query returns Hirlam 8 data from the database using a wci.read:

SELECT *
FROM wci.READ ( ARRAY['Hirlam norway'], -- Data provider name
               'POINT(10 60)', -- Geometry
               '1980-04-05 12:00:00',  -- Reference time
               'inside 1980-04-06 00:00:00 TO 1980-04-07 00:00:00', --Valid time
               ARRAY['air pressure', 'air temperature'], -- Parameter
               NULL, -- Level
               ARRAY[-1],  -- Data version
               NULL::wci.returnFloat -- Return type
             )

The above query returns Hirlam 8 data pressure and temperature data for the point closest to 10 degrees East, 60 degrees North that is valid for the twenty four hour time period of the 6th of April, 1980 and which was created (has the reference time) for the 5th of April, 12:00. The query returns all data that fulfills the above qualifications regardless of level, but only the latest version (dataversion) of the data available. Values will be returned as point data.

See Also

  • wci.begin
  • wci.end
  • wci.fetch
  • wci.write

wci.setDataProviderName

The function wci.setDataProviderName allows an administrator to set the data provider name of a data provider in the currently selected namespace of WDB. If another data provider name has already been set for the data provider in the namespace, this function will overwrite the old name.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setdataprovidername
(
	fromNameSpaceId			int,
	fromName				text,
	dataProviderName		text
)

Parameters

Parameter Description
fromNameSpaceId The nameSpace Id of the fromName.
fromName The name of the data provider to insert a name for. The name is taken from the fromNameSpaceId.
dataProviderName The data provider name to be set.


Expected Result

No return.

Example

To rename the data provider with the canonical name “michael” to “michel”, we would use:

SELECT wci.setdataprovidername( 'michael', 'michel' );

See Also

  • wci.adddataprovider
  • wci.adddataprovidertogroup
  • wci.addwciuser
  • wci.getdataprovider
  • wci.getdataprovidername

wci.setLevelParameterName

The function wci.setLevelParameterName allows an administrator to set the name of a level parameter in the currently selected namespace of WDB. If another level parameter name has already been set in the namespace, this function will overwrite the old name.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setlevelparametername
(
	canonicalName			text,
	levelParameterName		text
)

Parameters

Parameter Description
canonicalName The name of the level parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function.
levelParameterName The level parameter name to be set.


Expected Result

No return.

Example

To rename the parameter with the canonical name “hybrid level” to “HL”, we would use:

SELECT wci.setlevelparametername( 'hybrid level', 'HL' );

See Also

  • wci.addcodelevelparameter
  • wci.addmeasurelevelparameter
  • wci.getlevelparameter

wci.setPlaceName

The function wci.setPlaceName allows an administrator to set the place name of a place definition in the currently selected namespace of WDB. If another place name has already been set for the place definition in the namespace, this function will overwrite the old name.

Prerequisites

  • The user must have administrative access to the database.

Syntax

wci.setPlaceName
(
	canonicalName		text,
	placeName			text
)

Parameters

Parameter Description
canonicalName The canonical name of the place definition that you wish to change the place name for.
placeName The new place name of the place definition.


Expected Result

None.

Example

An example to set the name of the Hirlam 10 grid in the database:

SELECT wci.setplacename ( 'grid(5.75 -13.25, 0.1 0.1, 248 400, 50001)', 'hirlam 10km grid' );

See Also

  • wci.addplacepoint
  • wci.addplaceregulargrid
  • wci.addsrid
  • wci.getplacedefinition
  • wci.getplacename
  • wci.getplacepoint
  • wci.getplaceregulargrid

wci.setValueParameterName

The function wci.setValueParameterName allows an administrator to set the name of a value parameter in the currently selected namespace of WDB. If another value parameter name has already been set in the namespace, this function will overwrite the old name.

Prerequisites

  • The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setvalueparametername
(
	canonicalName			text,
	valueParameterName		text
)

Parameters

Parameter Description
canonicalName The name of the value parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function.
valueParameterName The value parameter name to be set.


Expected Result

No return.

Example

To rename the parameter with the canonical name “air temperature” to “2TM”, we would use:

SELECT wci.setvalueparametername( 'air temperature', '2TM' );

See Also

  • wci.addcodevalueparameter
  • wci.adddimensionlessvalueparameter
  • wci.addfunctionvalueparameter
  • wci.addmeasurevalueparameter
  • wci.getvalueparameter

wci.version

wci.version is a simple function that permits the user to retrieve version information about the WDB system.

Prerequisites

  • The user must have access to group role wdb_read

Syntax

wci.version ( )

Parameters

None.

Expected Result

The function returns a text with a string that describes the version of the WDB system in the PostgreSQL database.

Examples

The following query returns the WDB version:

SELECT wci.version ( )

The result is a single row of the text type containing the WDB version string.

See Also

  • wci.begin

wci.write

wci.write is function that can be utilized to write MHO data into the database.

The function is overloaded, and exists in several different versions depending on the input utilized.

Prerequisites

  • The user must be connected to the database
  • The user must have access to group role wdb_write
  • The user must have called wci.begin

Syntax

wci.write
(
	value          gid,
	placename      text,
	referencetime  timestamp without time zone,
	validtimerom   timestamp without time zone,
	validtimeto    timestamp without time zone
	valueparameter text,
	levelparameter text,
	levelFrom      float,
	levelTo        float
)
wci.write
(
	value          gid,
	placename      text,
	referencetime  timestamp without time zone,
	validtimerom   timestamp without time zone,
	validtimeto    timestamp without time zone
	valueparameter text,
	levelparameter text,
	levelFrom      float,
	levelTo        float
)
wci.write
(
          row           wci.returnGid
)

Parameters

Parameter Description
value The OID value to be retrieved
placename A text string identifying the geographical location that the data is being inserted for
referenceTime When the MHO data was created
validtimefrom What time is the MHO data valid for; starting time
validtimefrom What time is the MHO data valid for; ending time
valueparameter What MHO-parameters the user is interested in retrieving
levelparameter The parameter that describes the level designation
levelFrom What level (altitude/depth) the data is located at; starting point
levelTo What level (altitude/depth) the data is located at; ending point
row A wci.returnOid row. This function allows the user to take the result a query and write the same (or a slightly modified row) easily into the database.


Expected Result

The valueid of the inserted row.

See Also

  • wci.read
  • wci.begin
  • wci.end

Data Type Reference

This section provides an overview of the data types that are returned from the database through WCI; in particular the return rows used by the wci.read and wci.write calls.

wci.browsedataprovider

The wci.browsedataprovider data type is a simple row type used to return summarized information about the data providers of the rows currently stored in the database. The following table describes the attributes.

Order Attribute Description
0 dataprovidername The name of the data provider that the summary information is about.
1 referencetimefrom The earliest referencetime in the database for the dataprovider for which there exists data.
2 referencetimeto The latest referencetime in the database for the dataprovider for which there exists data.
3 numberoftuples The number of data rows that exist in the database for the given dataprovider.


wci.browseplace

The wci.browseplace data type is a simple row type used to return summarized information about the placenames of the rows currently stored in the database. The following table describes the attributes.

Order Attribute Description
0 placename The name of the placedefinition that the summary information is about.
1 referencetimefrom The earliest referencetime in the database for the placename for which there exists data.
2 referencetimeto The latest referencetime in the database for the placename for which there exists data.
3 numberoftuples The number of data rows that exist in the database for the given placename.


wci.browsereferencetime

The wci.browsereferencetime data type is a simple row type used to return summarized information about the referencetime of the rows currently stored in the database. The following table describes the attributes.

Order Attribute Description
0 referencetime The reference time that the summary information is about.
1 numberoftuples The number of data rows that exist in the database for the given referencetime.


wci.browsevalidtime

The wci.browsevalidtime data type is a simple row type used to return summarized information about the validtime of the rows currently stored in the database. The following table describes the attributes.

Order Attribute Description
0 validtimefrom The start time of the validtime period that is being summarized.
1 validtimeto The end time of the validtime period being summarized.
2 numberoftuples The number of data rows that exist in the database for the given validtime period or time point .


wci.browsevalueparameter

The wci.browsevalueparameter data type is a simple row type used to return summarized information about the valueparameters currently used by the rows in the database. The following table describes the attributes.

Order Attribute Description
0 valueparametername The name of the valueparameter that the summary information is about.
1 valueunitname The unit of the parameter in the database.
2 numberoftuples The number of data rows that exist in the database of the given valueparameter.


wci.browselevelparameter

The wci.browselevelparameter data type is a simple row type used to return summarized information about the levelparameters and level values currently stored by the rows in the database. The following table describes the attributes.

Order Attribute Description
0 levelparametername The name of the levelparameter that the summary information is about.
1 levelunitname The unit of the parameter in the database.
2 levelfrom The level from value of the rows in the database.
3 levelto The level to value of the rows in the database.
4 numberoftuples The number of data rows that exist in the database of the given level parameter and level value combination.


wci.infodataprovider

The wci.infodataprovider data type is a simple row type used to return metadata information about the dataproviders that can be stored in the database. The following table describes the attributes.

Order Attribute Description
0 dataprovidername The name of the dataprovider.
1 dataprovidertype The type of the dataprovider. This specifies whether the dataprovider is a person, computer system, meteorological station, or something else. It can also specify that the dataprovidername represents a group of other dataproviders.
2 spatialdomaindelivery The spatialdomaindelivery describes the spatial domain in which the dataprovider returns data. Examples are points and grids. The spatialdomaindelivery any is used to indicate that the dataprovider can store and return data in several formats on the database.
3 dataprovidercomment A text field that provides additional descriptive information about the dataprovider.
4 dataproviderstoretime Describes the time at which the dataprovider information was created.


wci.infoplace

The wci.infoplace data type is a simple row type used to return metadata information about the place definitions that can be stored in the database. The following table describes the attributes.

Order Attribute Description
0 placename The name of the place definition.
1 placegeometry The geometry (in WKT) that describes the place definition. For regular grids, this is a polygon of the four corners of the grid transformed into the default projection of the database.
2 placeindeterminatetype The place indeterminate type is used to describe imprecision or missing data in the place definition information.
3 placegeometrytype The placegeometrytype describes what type of geometry the row describes.
4 placestoretime Describes the time at which the place definition was created.


wci.inforegulargrid

The wci.inforegulargrid data type is a simple row type used to return detailed metadata information about the place definitions of the grid type that can be stored in the database. The following table describes the attributes.

Order Attribute Description
0 placename The name of the place definition.
1 numberX The number of points along the X axis of the grid (i.e., the width).
2 numberY The number of points along the Y axis of the grid (i.e., the height).
3 incrementX The distance between two points on the X axis of the grid in the original projection of the grid.
4 incrementY The distance between two points on the Y axis of the grid in the original projection of the grid.
5 startX The starting point (lower left corner) of the grid on the X axis in the original projection of the grid.
6 startY The starting point (lower left corner) of the grid on the Y axis in the original projection of the grid.
7 projDefinition The proj.4 string that defines the original projection of the grid. Since the structure of a grid is not reprojected, this information maya be useful if you need to deal with the grid information directly.


wci.infovalueparameter

The wci.infovalueparameter data type is a simple row type used to return metadata information about the value parameters that can be stored in the database. The following table describes the attributes.

Order Attribute Description
0 valueparametername The name of the value parameter.
1 valueunitname The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible.


wci.infolevelparameter

The wci.infolevelparameter data type is a simple row type used to return metadata information about the level parameters that can be stored in the database. The following table describes the attributes.

Order Attribute Description
0 levelparametername The name of the level parameter.
1 levelunitname The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible.


wci.returnFloat

The wci.returnFloat data type is a simple row type used for returning floating-point data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnFloat; including the ordering of the attributes in the type.

Order Attribute Description
0 value The floating point value returned by the query
1 data provider name The name of the data provider of the value (as defined within the dataprovidernamespace selected)
2 place name The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed.
3 place geometry The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4 referencetime The time of reference for the value returned
5 validtime from The first point in time for which the value is valid
6 validtime to The last point in time for which the value is valid
7 validtime indeterminate code The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact, which implies that the validtime interval given is precise.
8 value parameter name The parameter name for the value returned (as defined within the parameter name space selected)
9 value parameter unit The measurement unit for the value returned
10 level parameter name The parameter name for the level of the value returned (as defined within the parameter name space selected)
11 level unit name The measurement unit for the level of the value returned
12 level from The lower value of the level
13 level to The upper value of the level
14 level indeterminate code The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15 data version The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members).
16 confidence code Quality marker (not currently used)
17 value store time The time when the data was inserted into the database
18 value id The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19 value type The type of the value returned. Together with the valueid, this constitutes a key of the WDB value


wci.returnGid

The wci.returnGid data type is a simple row type used for returning data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnGid; including the ordering of the attributes in the type.

Order Attribute Description
0 value The grid ID (GID) of the value being returned
1 data provider name The name of the data provider of the value (as defined within the dataprovidernamespace selected)
2 place name The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed
3 place geometry The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4 referencetime The time of reference for the value returned
5 validtime from The first point in time for which the value is valid
6 validtime to The last point in time for which the value is valid
7 validtime indeterminate code The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact, which implies that the validtime interval given is precise.
8 value parameter name The parameter name for the value returned (as defined within the parameter name space selected)
9 value parameter unit The measurement unit for the value returned
10 level parameter name The parameter name for the level of the value returned (as defined within the parameter name space selected)
11 level unit name The measurement unit for the level of the value returned
12 level from The lower value of the level
13 level to The upper value of the level
14 level indeterminate code The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15 data version The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members).
16 confidence code Quality marker (not currently used)
17 value store time The time when the data was inserted into the database
18 value id The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19 value type The type of the value returned. Together with the valueid, this constitutes a key of the WDB value


Examples

You can find a number of examples using SQL, perl, java, R-script and C++ in the source package of WDB, under the examples directory.

Frequently Asked Questions

This section is for a list of frequently asked questions about WCI.

Known Problems, Bugs, and Limitations

The following page describes some of the known problems and limitations of the WCI interface, and how to deal with them.

Limit of 100,000 rows returned by wci.read from a single grid

The wci.read function is limited to returning no more than 100,000 rows from a single grid operation. If you need to retrieve a greater number of values from one grid in the database, you should use wci.fetch to retrieve the Grid object directly and perform the retrieval manually.

wdb/manuals/wdb_call_interface.txt · Last modified: 2012-04-04 19:34:02 by michaeloa