Contents

WDB Call Interface
Updated 911 Days AgoPublic

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

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 Guide.

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
ParameterDescription
parameterNameThe 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.
parameterReferenceReference 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
ParameterDescription
parameterNameThe 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.
parameterReferenceReference 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
ParameterDescription
dataProviderNameThe 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.
dataProviderTypeThe 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
domainDeliveryThe 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
dataprovidercommentSupplementary 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
ParameterDescription
dataProviderNameThe data provider name to be added to the specified group.
dataProviderGroupThe 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
ParameterDescription
parameterNameThe 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.
parameterDescriptionA 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
ParameterDescription
parameterUsageThe usage dimension of the value parameter.
parameterUnitThe SI unit of the value parameter. The unit is used to determine the physical dimension of the function value parameter.
parameterFunctionThe function of the value parameter.
parameterQuantityThe 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
ParameterDescription
levelParameterUsageA usage dimension for a level parameter.
levelDescriptionA 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
ParameterDescription
measureThe measure being described.
distancepowerThe distance dimension of the measure. Use 0 to denote none.
masspowerThe mass dimension of the measure. Use 0 to denote none.
timepowerThe time dimension of the measure. Use 0 to denote none.
luminositypowerThe luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpowerThe electric current dimension of the measure. Use 0 to denote none.
temperaturepowerThe temperature dimension of the measure. Use 0 to denote none.
substancepowerThe substance dimension of the measure. Use 0 to denote none.
anglepowerThe 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
ParameterDescription
parameterUsageThe usage dimension of the level parameter.
parameterUnitThe 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
ParameterDescription
parameterUsageThe usage dimension of the value parameter.
parameterUnitThe SI unit of the value parameter. The unit is used to determine the physical dimension of the measure value parameter.
parameterQuantityThe 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
ParameterDescription
parameterFunctionTypeThe name of the function type being defined for value parameters.
parameterFunctionDescriptionA 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
ParameterDescription
placeNameThe 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.
placeGeometryThe 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
ParameterDescription
placeNameThe 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.
placeGeometryThe 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
ParameterDescription
placeNameThe 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.
numXThe number of points along the X axis of the grid.
numYThe number of points along the Y axis of the grid.
incXThe distance between any two points on the X axis of the grid. The unit of measure is given by the projection.
incYThe distance between any two points on the Y axis of the grid. The unit of measure is given by the projection.
startXThe origin X point (lower left corner) of the grid in the specified projection.
startYThe origin Y point (lower left corner) of the grid in the specified projection.
projectionThe 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
ParameterDescription
nameA descriptive name for the projection.
projectionThe 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
ParameterDescription
unitNameThe UCUM designation of the unit.
unitTypeThe type of the unit. Permitted types are: 'SI Unit', 'Base Unit', and 'Conventional Unit'. Most units should be defined as the latter.
measureThe associated measure of the unit.
descriptionA description of the unit. For most units, this will simply be the unabbreviated (i.e., full) form of the unit name.
siunitconversioncoefficientThe coefficient to multiply the value with in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term
siunitconversiontermThe 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
ParameterDescription
valueParameterUsageA usage dimension for a value parameter.
valueDescriptionA 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
ParameterDescription
dataProviderNameThe 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
ParameterDescription
userThe userid to initialize the connection with
dataprovidernamespaceidThe namespace to be used for dataprovider names in the session
placenamespaceidThe namespace to be used for place names in the session
parameternamespaceidThe 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.

AttributeDescription
nameThe name of the software package.
softwareversionThe version of the software.
packageversionThe version of the package; this is a sequential number independent of the software version.
descriptionA description of the software package.
installtimeThe 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
ParameterDescription
objectidThe object ID of the binary object to be returned, as given by a wci.read call
returnTypeWhat 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
ParameterDescription
parameterThe 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

AttributeDescription
levelparameteridThe internal parameter ID used in WDB.
levelcodeparameternameThe canonical name of the level parameter.
codeparameterreferenceThe reference information for the level code.
parameternamespaceidThe parameter name space ID of the query.
levelparameternameThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
valueparameteridThe internal parameter ID used in WDB.
valuecodeparameternameThe canonical name of the value parameter.
codeparameterreferenceThe reference information for the value code.
parameternamespaceidThe parameter name space ID of the query.
valueparameternameThe 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
ParameterDescription
dataProviderNameThe 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.

AttributeDescription
dataprovideridThe internal data provider ID used in WDB.
dataprovidertypeThe type classification of the data provider in WDB.
spatialdomaindeliveryThe spatial domain of data delivered by this data provider; either point data, gridded data, or both.
dataprovidernamespaceidThe currently selected data provider name space.
dataprovidernameThe data provider name of the data provider in this namespace.
dataprovidernameleftsetAn internal WDB code used for grouping.
dataprovidernamerightsetAn internal WDB code used for grouping.
dataproviderstoretimeThe store time of this data provider; i.e., when it was inserted into the database.
dataprovidercommentAdditional 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
ParameterDescription
dataProviderNameThe 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.

AttributeDescription
dataprovideridThe internal data provider ID used in WDB.
dataprovidernamespaceidThe currently selected data provider name space.
dataprovidernameThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
valueparameteridThe internal parameter ID used in WDB.
valuedimensionlessparameternameThe canonical name of the value parameter.
valueparameterdescriptionA description of the value parameter.
valueunitnameThe unit of the value parameter.
parameternamespaceidThe parameter name space ID of the query.
valueparameternameThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
valueparameteridThe internal parameter ID used in WDB.
parameterfunctiontypeThe parameter function.
valueparameterusageThe value parameter usage.
parameterquantitytypeThe quantity type of the value parameter.
measureThe measure of the value parameter.
valueunitnameThe unit name used for the value parameter.
parameternamespaceidThe parameter name space ID of the query.
valueparameternameThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
levelparameteridThe internal parameter ID used in WDB.
parameternamespaceidThe parameter name space ID of the query.
levelparameternameThe 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.
levelunitnameThe 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
ParameterDescription
usageThe 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.

AttributeDescription
levelparameterusageThe level parameter usage descriptor.
levelparameterusagedescriptionA 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
ParameterDescription
measureThe 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.

AttributeDescription
measureThe measure being described.
distancepowerThe distance dimension of the measure. Use 0 to denote none.
masspowerThe mass dimension of the measure. Use 0 to denote none.
timepowerThe time dimension of the measure. Use 0 to denote none.
luminositypowerThe luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpowerThe electric current dimension of the measure. Use 0 to denote none.
temperaturepowerThe temperature dimension of the measure. Use 0 to denote none.
substancepowerThe substance dimension of the measure. Use 0 to denote none.
anglepowerThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
levelparameteridThe internal parameter ID used in WDB.
levelparameterusageThe usage of the level parameter.
measureThe measure of the level parameter.
levelunitnameThe unit of the level parameter.
parameternamespaceidThe parameter name space ID of the query.
levelparameternameThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
valueparameteridThe internal parameter ID used in WDB.
valueparameterusageThe usage of the value parameter.
parameterquantitytypeThe quantity type of the value parameter.
measureThe measure of the value parameter.
valueunitnameThe unit of the value parameter.
parameternamespaceidThe parameter name space ID of the query.
valueparameternameThe 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
ParameterDescription
typeThe 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.

AttributeDescription
parameterfunctiontypeThe parameterfunctiontype being described.
parameterfunctiondescriptionA 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
ParameterDescription
placenameThe 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.

AttributeDescription
placeidThe internal place ID used in WDB.
placegeometrytypeThe place geometry of the place definition. Currently points and grids are supported
placegeometryThe 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.
placeindeterminatecodeThe indeterminate code for the place definition.
placenamespaceidThe name space of the query.
placenameThe place name of the place definition.
originalsridThe original SRID of the place definition. This is particularly important to keep track of for grids.
placestoretimeThe 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
ParameterDescription
placenameThe placename that you require information for. NULL returns all place names in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.
numberxThe number of points along the x axis in the regular grid.
numberyThe number of points along the y axis in the regular grid.
incrementxThe 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.
incrementyThe increment distance on the y axis.
startxThe starting point of the grid on the x axis of the original Proj.4 projection.
startyThe starting point of the grid on the y axis of the original Proj.4 projection.
projdefinitionThe original PROJ.4 projection of the place definition.
Expected Result

The list of place grids.

AttributeDescription
placeidThe internal place ID used in WDB.
placenamespaceidThe name space of the query.
placenameThe 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
ParameterDescription
placenameThe 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.

AttributeDescription
placeidThe internal place ID used in WDB.
placegeometrytypeThe place geometry of the place point. Currently points and grids are supported
placegeometryThe geometry of the place point.
placeindeterminatecodeThe indeterminate code for the place point.
placenamespaceidThe name space of the query.
placenameThe place name of the place point.
originalsridThe original SRID of the place point.
placestoretimeThe 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
ParameterDescription
placenameThe 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.

AttributeDescription
placeidThe internal place ID used in WDB.
placegeometrytypeThe place geometry of the place definition. Currently points and grids are supported
placegeometryThe geometry of the place definition.
placeindeterminatecodeThe indeterminate code for the place definition.
placenamespaceidThe name space of the query.
placenameThe place name of the place definition.
numberxThe number of points along the x axis in the regular grid.
numberyThe number of points along the y axis in the regular grid.
incrementxThe 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.
incrementyThe increment distance on the y axis.
startxThe starting point of the grid on the x axis of the original Proj.4 projection.
startyThe starting point of the grid on the y axis of the original Proj.4 projection.
originalsridThe original SRID of the place definition. This is particularly important to keep track of for grids.
projdefinitionThe original PROJ.4 projection of the place definition.
placestoretimeThe 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
ParameterDescription
projstrThe 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.

AttributeDescription
sridThe spatial reference ID. An integer value that uniquely identifies the Spatial Referencing System (SRS) within the database.
auth_nameThe 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_sridhe 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.
srtextThe Well-Known Text representation of the Spatial Reference System. WDB ignores this column and always inserts NULL.
proj4textThis 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
ParameterDescription
unitThe 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.

AttributeDescription
unitnameThe name (context-sensitive UCUM designation) of the unit.
unittypeThe type of the unit.
measureThe measure of the unit, if any.
descriptionA description of the unit.
siunitconversioncoefficientThe coefficient to multiply the value with to get the SI unit (if any). The formula is (value * coefficient) + term
siunitconversiontermThe 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
ParameterDescription
parameterThe 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.

AttributeDescription
valueparameteridThe internal parameter ID of the value parameter.
parameternamespaceidThe currently selected parameter name space.
valueparameternameThe name of the valueparameter in the name space.
valueparameterunitThe 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
ParameterDescription
dataProvidersList of data providers for the MHO data to be retrieved
placeA 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.
referenceTimeWhen the MHO data was created
validtimeWhat time is the MHO data valid for
parametersWhat MHO-parameters the user is interested in retrieving
levelWhat level (altitude/depth) the data is located at
dataVersionWhat version of the data should be returned
returnTypeWhat 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
ParameterDescription
fromNameSpaceIdThe nameSpace Id of the fromName.
fromNameThe name of the data provider to insert a name for. The name is taken from the fromNameSpaceId.
dataProviderNameThe 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
ParameterDescription
canonicalNameThe 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.
levelParameterNameThe 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
ParameterDescription
canonicalNameThe canonical name of the place definition that you wish to change the place name for.
placeNameThe 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
ParameterDescription
canonicalNameThe 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.
valueParameterNameThe 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
ParameterDescription
valueThe OID value to be retrieved
placenameA text string identifying the geographical location that the data is being inserted for
referenceTimeWhen the MHO data was created
validtimefromWhat time is the MHO data valid for; starting time
validtimefromWhat time is the MHO data valid for; ending time
valueparameterWhat MHO-parameters the user is interested in retrieving
levelparameterThe parameter that describes the level designation
levelFromWhat level (altitude/depth) the data is located at; starting point
levelToWhat level (altitude/depth) the data is located at; ending point
rowA 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.

OrderAttributeDescription
0dataprovidernameThe name of the data provider that the summary information is about.
1referencetimefromThe earliest referencetime in the database for the dataprovider for which there exists data.
2referencetimetoThe latest referencetime in the database for the dataprovider for which there exists data.
3numberoftuplesThe 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.

OrderAttributeDescription
0placenameThe name of the placedefinition that the summary information is about.
1referencetimefromThe earliest referencetime in the database for the placename for which there exists data.
2referencetimetoThe latest referencetime in the database for the placename for which there exists data.
3numberoftuplesThe 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.

OrderAttributeDescription
0referencetimeThe reference time that the summary information is about.
1numberoftuplesThe 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.

OrderAttributeDescription
0validtimefromThe start time of the validtime period that is being summarized.
1validtimetoThe end time of the validtime period being summarized.
2numberoftuplesThe 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.

OrderAttributeDescription
0valueparameternameThe name of the valueparameter that the summary information is about.
1valueunitnameThe unit of the parameter in the database.
2numberoftuplesThe 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.

OrderAttributeDescription
0levelparameternameThe name of the levelparameter that the summary information is about.
1levelunitnameThe unit of the parameter in the database.
2levelfromThe level from value of the rows in the database.
3leveltoThe level to value of the rows in the database.
4numberoftuplesThe 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.

OrderAttributeDescription
0dataprovidernameThe name of the dataprovider.
1dataprovidertypeThe 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.
2spatialdomaindeliveryThe 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.
3dataprovidercommentA text field that provides additional descriptive information about the dataprovider.
4dataproviderstoretimeDescribes 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.

OrderAttributeDescription
0placenameThe name of the place definition.
1placegeometryThe 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.
2placeindeterminatetypeThe place indeterminate type is used to describe imprecision or missing data in the place definition information.
3placegeometrytypeThe placegeometrytype describes what type of geometry the row describes.
4placestoretimeDescribes 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.

OrderAttributeDescription
0placenameThe name of the place definition.
1numberXThe number of points along the X axis of the grid (i.e., the width).
2numberYThe number of points along the Y axis of the grid (i.e., the height).
3incrementXThe distance between two points on the X axis of the grid in the original projection of the grid.
4incrementYThe distance between two points on the Y axis of the grid in the original projection of the grid.
5startXThe starting point (lower left corner) of the grid on the X axis in the original projection of the grid.
6startYThe starting point (lower left corner) of the grid on the Y axis in the original projection of the grid.
7projDefinitionThe 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.

OrderAttributeDescription
0valueparameternameThe name of the value parameter.
1valueunitnameThe 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.

OrderAttributeDescription
0levelparameternameThe name of the level parameter.
1levelunitnameThe 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.

OrderAttributeDescription
0valueThe floating point value returned by the query
1data provider nameThe name of the data provider of the value (as defined within the dataprovidernamespace selected)
2place nameThe 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.
3place geometryThe geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4referencetimeThe time of reference for the value returned
5validtime fromThe first point in time for which the value is valid
6validtime toThe last point in time for which the value is valid
7validtime indeterminate codeThe 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.
8value parameter nameThe parameter name for the value returned (as defined within the parameter name space selected)
9value parameter unitThe measurement unit for the value returned
10level parameter nameThe parameter name for the level of the value returned (as defined within the parameter name space selected)
11level unit nameThe measurement unit for the level of the value returned
12level fromThe lower value of the level
13level toThe upper value of the level
14level indeterminate codeThe level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15data versionThe 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).
16confidence codeQuality marker (not currently used)
17value store timeThe time when the data was inserted into the database
18value idThe ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19value typeThe 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.

OrderAttributeDescription
0valueThe grid ID (GID) of the value being returned
1data provider nameThe name of the data provider of the value (as defined within the dataprovidernamespace selected)
2place nameThe 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
3place geometryThe geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4referencetimeThe time of reference for the value returned
5validtime fromThe first point in time for which the value is valid
6validtime toThe last point in time for which the value is valid
7validtime indeterminate codeThe 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.
8value parameter nameThe parameter name for the value returned (as defined within the parameter name space selected)
9value parameter unitThe measurement unit for the value returned
10level parameter nameThe parameter name for the level of the value returned (as defined within the parameter name space selected)
11level unit nameThe measurement unit for the level of the value returned
12level fromThe lower value of the level
13level toThe upper value of the level
14level indeterminate codeThe level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15data versionThe 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).
16confidence codeQuality marker (not currently used)
17value store timeThe time when the data was inserted into the database
18value idThe ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19value typeThe 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.

Last Author
michaeloa
Subscribers
None
Projects
None