====== WDB Call Interface User Manual ====== **Abstract** WDB is a data storage solution for weather and water data based on the PostgreSQL object-relational database system. The system utilizes PostGIS for GIS (Geographic Information Systems) support and handles regular grids (e.g., forecast fields) and point (e.g., observation) data. This is the User's Manual for WDB Call Interface. ===== Introduction ===== The WDB Call Interface (WCI) is the official API used for retrieving data from the WDB system. ==== About this Manual ==== This manual is intended for system designers, application developers and programmers. It describes in technical terms how weather data can be retrieved from the WDB system through the WCI. It is assumed that the reader has some familiarity with databases and weather data. For a more elaborate description of the vision and system architecture of the WDB system, see the WDB Developer's Manual. ==== Intended Usage ==== WCI is intended to be used for retrieving weather data (e.g., temperature, air pressure, etc.) for a geographic point or area, given an altitude interval and a time or time interval. It is possible to retrieve individual data values or huge quantities of data using a single API. ==== Outline ==== This document is structured as follows: * Key Concepts: introduction to the concepts and terms used in the documentation * Using the WCI: an introduction to how the WCI is used * Function Reference: reference documentation for each of the WCI functions * Data Types Reference: reference documentation for the WCI data types * Examples: Example programs for WCI * FAQ: Frequently asked questions * Known bugs and limitations ===== Key Concepts ===== This section provides an overview of the WCI, including some important definitions and explanations. ==== Overview ==== WCI is an API designed to retrieve weather data from the WDB system. The WCI API resides on the database server. All function calls on WCI are executed as SQL statements. The SQL statements can be executed through a dedicated SQL client application, such as psql, pgadmin3, DbVisualizer, or by an application program through a database API such as JDBC, ODBC, libpqxx, etc. The WCI is thus not linked into the application program itself, but is a component of the database. A data item in WDB could be an observation, a forecast, an analysis, etc. Each item consists of a value and a number of dimensions that describe the value. A dimension could be a description of the data item (e.g., temperature), its geographic position, its altitude (or depth), the time the data item was created, the origin of the data item, etc. In order to access the data items in WDB, the user should have an understanding of the dimensions as they are the entry point into the database. When data is retrieved from the database, a set of search criteria is given for each of the WCI dimensions. If the search criteria for a dimension is not specified (i.e., all NULLs), it is assumed the user wants to retrieve all data items, regardless of their dimension description. Please do not attempt this unless the database you are querying is extremely small. In the context of WCI search criteria, NULL is always interpreted to mean "ALL". The last parameter of a WCI function call that is intended to return data is always reserved for specifying the data type to be returned (this is because most functions are overloaded to return many different forms of data. By convention, this parameter is usually given as a NULL cast to the relevant data type; for example: NULL::wci.browsereferencetime The dimensions are described in the following sections. ==== Data Provider ==== The Data Provider identifies the source of the data; literally, //the entity that provides the data//. Where multiple sources could be identified as the source of the data, the entity that can be identified closest to the creation of the data item at the time of loading is usually used. A data provider can be a software process (e.g., Hirlam), a meteorological or climate station, an aircraft, or a person. A data provider is identified by a DataProviderName. DataProviderNames are used to search for the data. For convenience, Data Providers may be collected into groups; e.g., the DataProviderName "Hirlam" might be used to search for any of the various Hirlam processes: "Hirlam 4", "Hirlam 8", etc. When searching for data, the user may specify a single DataProviderName, a list of DataProviderNames (specified using an ARRAY constructor), or NULL. NULL indicates that the user wants all data items, regardless of the data source. DataProviderNames exist within a data provider namespace. A namespace can be defined by the WDB administrator, in order to permit the user or an application to retrieve data in an accustomed language or code set. The default namespace of WDB is the DataProviderNameSpaceId 0, and is always based on English language names and international standard codes. The data provider namespace being used in a querying session can be defined by the user when starting up the session. To retrieve all of the DataProviderNames (excluding data provider groups) that are currently stored in the database for the currently specified namespace, the following wci.browse function call could be used: SELECT * FROM wci.browse( NULL::wci.browsedataprovider ); To retrieve all of the DataProviderNames (including data provider groups) that the database currently has the capacity to store and display in the currently specified namespace, the following wci.info function call could be used: SELECT * FROM wci.getDataProvider( NULL ); ==== Place (Geographic Location) ==== The place (geographic location) of a data item is the position of the item on the earth in a 2D space. In WDB, the geographic location is by default specified using longitude and latitude in a WGS84 coordinate system (though this can be changed when the database is set up; consult your system administrator). The geographic dimension is specified using a geometry object and can be either a point or a polygon. In addition to using geometry objects to retrieve data, the user can also use a PlaceName - a pre-specified name that defines a geometry object in the database - to specify location. As for DataProviderName, PlaceNames exist within a place namespace that can be defined by the WDB administrator. The default namespace of WDB is the PlaceNameSpaceId 0; defined in international english. As for the data provider namespace, the place namespace can be defined by the user when starting up the session. To retrieve the full list of the PlaceNames for the data values currently being stored in the database, use the following wci.browse function call: SELECT * FROM wci.browse( NULL::wci.browseplace ); At the same time as the user specifies a location to retrieve data from, it is also possible to specify an interpolation option for location calculations. These permit the user a great deal of flexibility in searching. Currently, interpolations such as "exact", "nearest" (retrieve the data value closest to the specified place), and "bilinear" (retrieve the closest data values and perform a bilinear interpolation of those values) are implemented. The form of place specification then becomes one of the two following: 'Oslo' 'nearest Oslo' 'POINT(61 9)' 'bilinear POINT(61 9)' Specifying NULL for the place definition of a query is logically equivalent to asking for all of the data items in the database, irrespective of their location. To retrieve all of the place names that are currently registered in the database, the following WCI function call can be used: SELECT * FROM wci.getPlaceDefinition( NULL ); ==== Reference Time ==== The reference time of a data item is the moment when the data item is referenced from. For forecast data, this would typically be the reference time of the data values the forecast is based upon; for observation data, it would typically be the time when the observation data was recorded. When searching for data, the user specifies the reference time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the reference time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser. To retrieve a list of the reference times currently being stored in the database, use the wci.browse functionality: SELECT * FROM wci.browse( NULL::wci.browsereferencetime ); In addition to time points, it is also possible for the user to specify time periods using a variety of keywords. The keywords are: exact (default), before, after, inside, and contains. And interval can be specified using two timestamps and separating them with the keyword TO, or a timestamp and a duration separated by the keyword FOR. As examples, consider: exact 2009-03-31T11:20:00+00 Denotes the specific time point of 11:20 UTC, on the 31st of March, 2009. The keyword "exact" is actually redundant, as this is the default interpretation of a timestamp in WCI. before 2009-03-31T11:20:00+00 Denotes that the user wants to return all data for the time period prior to the time point of 11:20 UTC, on the 31st of March, 2009. after 2009-03-31T11:20:00+00 Denotes that the user wants to return all data for the time period after the time point of 11:20 UTC, on the 31st of March, 2009. inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00 Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later. inside 2009-03-31T11:20:00+00 FOR 2 months Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later. ==== Valid Time ==== The valid time of a data item is the time period for which the data item is valid. The valid time is always stored in the database as a time interval. When searching for data, the user specifies the valid time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the valid time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser. As usual, the list of valid times stored in the database can be retrieved using the wci.browse functionality. SELECT * FROM wci.browse( NULL::wci.browsevalidtime ); Time is specified in the same way for time periods as for time points. Examples of how the qualifiers should be interpreted are given below: exact 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00 The exact keyword returns only time periods that match precisely with the time period specified. before 2009-03-31T11:20:00+00 The before keyword returns only time periods that end before the specified time point. In other words, the time period from 2009-03-29 to 2009-03-30 would be returned by the query but the time period from 2009-03-29 to 2009-04-01 would not. after 2009-03-31T11:20:00+00 The after keyword returns only time periods that start after the specified time point. inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00 The inside keyword for time periods is true if the time period both starts and ends within the designated time (the time point specified inclusive). It does not return time periods that merely overlap (i.e., where only the start time or the end time are within the given time period). contains 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00 The contains keyword returns all the data with valid times beginning prior to the specified time and ending after the specified time. Semantics are inclusive, so a valid time that matches exactly would be returned as a row by this query. ==== Value Parameter ==== Each data value can be described using a "value parameter". The value parameter is a name that describes the physics or code table basis of the parameter value. The value parameter concept in WCI is broadly similar to the concept of meteorological parameter used in, e.g., GRIB files. The user searches the database for a specific parameter in the database using the ValueParameterName. ValueParameterNames are specified within a parameter namespace. As with the other namespaces, the ParameterNameSpaceId 0 is reserved for the default WDB namespace, and is based on international english. Additional namespaces can be defined by the administrator of the database. To retrieve a list of the value parameters currently being stored in the database, use the wci.browse functionality: SELECT * FROM wci.browse( NULL::wci.browsevalueparameter ); To list all of the value parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used: SELECT * FROM wci.getValueParameter( NULL ); ==== Level ==== The //Level// dimension is normally used to designate the altitude or depth of the data value. Level is designated using a level interval (height from and to) and a level parameter (e.g., height above sea level, pressure). The level definition can be prefixed with a level interpolation option that permits the user a large degree of flexibility in expressing searches. Levels are specified using a level specification in string form that is parsed by the WCI. The level designation in the WCI queries is a string. The form of the level designation when querying the database is as follows: interpolation levelFrom TO levelTo leveparametername The interpolations available are //exact//, //below//, //above//, //inside//, and //any//. The default interpolation is exact (specifying the interpolation is optional). One may also omit the //TO levelTo// construction if the level being specified is a point. Specifying //any// for the level interpolation is logically equivalent to specifying a NULL for the level; i.e., it retrieves all data items regardless of their level (height). The level parameter is specified using a LevelParameterName. LevelParameterNames are specified within the parameter namespace. Consequently, it is not possible to mix usage of ValueParameterNames and LevelParameterNames from different namespaces without defining a new parameter namespace. The default WDB ParameterNameSpaceId is 0 and is based on international english. Examples of level designations are given below: exact 2 height above 0 height above mean sea level distance inside 300 TO 500 isobaric surface pressure To retrieve a full list of the levels and level parameters currently being stored in the database, use the wci.browse functionality: SELECT * FROM wci.browse( NULL::wci.browselevelparameter ); To list all of the level parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used: SELECT * FROM wci.getLevelParameter( NULL ); ==== Data Version ==== There can be several different versions of the same data value that is valid for the same time, position, etc. This can happen with probability forecast calculations or when a data value is edited (in which case the new value may often be inserted with a higher data version). A data version is always a positive whole number. The user may specify one or several data versions as search criteria in WCI, as well as NULL. NULL indicates that the user wants all versions of the data items specified. In addition, the user may specify the data version as a negative number; e.g., //-1//. Specifying //-1// retrieves the maximum data version in the database (i.e., the most recent version of the data item), //-2// retrieves the second most recent, and so on. There is no wci.browse functionality to list all of the data versions of the data in the database. ===== Using the WCI ===== This section gives an overview on how to use the WCI to retrieve data values from WDB. ==== Outline ==== The following list provides a brief overview of the actions that the user takes in order to retrieve data from WCI. * Create a connection to the database * Initialize WCI * Read data from WDB using WCI functions (one or more times) * Release WCI * Close database connection ==== Open a connection ==== To enable communication with WCI, the user must open a connection to the database. How this is done depends very much on the application or API that is being used (consult the documentation of the program or API for information). Using libpq, connection_ = PQconnectdb("dbname=wdb user=myuser host=localhost"); The connection must be open and valid as long as commands are being sent and data retrieved from the database. It is worth noting that connections are a resource; the database will have limits on how many connections can be open at the same time. This is particularly important for massively multi-user applications (e.g., web applications). In such cases, the database connections must be managed with some care. There is also an amount overhead involved with setting up a connection, so it will always be more efficient to connect once and perform multiple database operations, than to connect repeatedly for each operation. ==== Initialize WCI ==== Before WCI may be used by the user, it must be initialized. SELECT wci.begin('myuser'::name, 0::integer, 0::integer, 0::integer); The username is used to identify the user with WCI (this is used in setting up internal WCI variables). The three following numbers are the namespace codes for data provider namespace, place name space, and parameter name space. The wci.begin can also be called without setting these three variables, in which case they are set to the default (usually 0, 0, 0) by the system. The username of the wci user can be a different identity than the one the user connected with (always assuming, of course, that your user has appropriate rights). This allows, for instance, for a single system to act as a multiplexing front-end to retrieve data available from several distinct users. Name spaces are used to identify what set of names should be used for searching the database. While the user is in a namespace, only the data defined in that namespace is visible to the user. If the user should wish, for some reason, to combine data from different namespaces within an application, it will be necessary to call wci.begin repeatedly; once for each time the application needs to change its namespace. ==== Read from the WCI ==== As soon as the user has initialized WCI using wci.begin, the database is ready for retrieval of data. Data is retrieved using the wci.read function, and data is searched for by setting the appropriate dimensions in that call. === Reading Point Data from WCI === The wci.read function is overloaded to permit the user to read either point data or binary data (entire grids) from the database. The last parameter in the wci.read function allows the user to specify the return type of the query. To return point data values, the user specifies wci.returnFloat. SELECT * FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name 'POLYGON((10 60,11 60,11 61,10 61,10 60))', -- Location 'inside 1980-01-01 12:00:00Z TO 1980-01-01 18:00:00Z', -- Reference time NULL, -- Valid Time ARRAY['air temperature'], -- Value Parameter '2 height', -- Level ARRAY[-1], -- Data version NULL::wci.returnfloat -- Return type ) The above query returns Hirlam data for a specific region (given by the place geometry), whose referencetime is on or between 12:00 to 18:00 on January 1, 1980; the query will return data for any valid times, for any air temperature. It will return data at 2 metre above ground, but only the latest version of such data. Values will be returned as point data. The data provider, place definition, value parameter and level parameter must all be defined within the namespaces given in the wci.begin call that preceded the wci.read call. In this particular case, the place definition is a geometry definition, but it would also have been possible to use a placename. Consider, for example, the following query: SELECT * FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name 'oslo', -- Location '1980-01-01 12:00:00Z', -- Reference time 'inside 1980-01-02 12:00:00 TO 1980-01-12 12:00:00', -- Valid Time ARRAY['%precipitation%'], -- Value Parameter NULL, -- Level NULL, -- Data version NULL::wci.returnfloat -- Return type ) The above call returns all precipitation parameters valid for the 10 days following the given referencetime measured at the nearest point to oslo. Oslo, in this case, is a place name usually defined as a geographical point within the database. Prefixing the place name is the interpolation that we wish to use when retrieving points; we could also have used any of the alternatives defined in the reference manual below. Note the use of SQL wildcard characters in the value parameter; although these slow down queries (since wildcard searching is not as efficient as a straight comparison), it is possible to use the wci.read call in this way. Note also that names can be written in upper or lower case; the wci.read function call is not case-sensitive. == Return values == The return value from this call is one row for each value. This means that if you have chosen an interpolation type that will return several values for each grid, you will get many rows for each grid. The actual data value is given in the column "value". In some cases this may have a NULL value. This means that the there exists a data field for your query, and the point(s) you requested is inside the data's grid, but that grid point has explicitly gotten a "not defined" value. === Reading Grid Data from WCI === Reading grid data from the database is a two-step process. First the user retrieves the Grid ID with wci.read function (with wci.returnGId), and then the grid itself can be retrieved using the wci.fetch function call. SELECT * FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name 'hirlam 10km grid', -- Location description '1980-01-01 12:00:00Z', -- Reference time NULL, -- Valid Time (returns all forecasts) ARRAY['air temperature'], -- Value Parameter '2 height', -- Level ARRAY[-1], -- Data version NULL::wci.returngid -- Return type ) The above query returns the list of grids available for Hirlam data, defined on the hirlam 10km grid (i.e., if there were data on 20km or 4km grids, these would not be returned), whose referencetime is 12:00 on January 1, 1980. The query will return all grid references to air temperature forecasts for the above configuration. Grid IDs are essentially 8-byte integers, that are then passed to the wci.fetch command, as given below: SELECT * FROM wci.fetch ( 7411403, -- Grid ID (bigint) NULL::wci.grid -- Return Type ) The above call returns a single row, containing a binary string containing the actual grid data. It also includes additional information detailing the configuration of the grid. For details about the wci.fetch call, see the function reference. == Return values == The return value from this call is one row for each grid. The number given in the "value" column may be used as input argument for a wci.fetch call. ==== Release WCI ==== Once the user has finished retrieving data using WCI, it is a good idea to close down WCI. SELECT wci.end(); This is not strictly necessary, but allows the system to graciously deallocate resources and reset any settings that may have been changed by WCI. ==== Close Connection ==== Closes down the connection to the database, freeing up the resources on the database to be used by other applications. Using libpq, PQfinish(connection_); ===== Function Reference ===== The following sections provide a list of the functions available for usage through the WDB Call Interface. ==== wci.addCodeLevelParameter ==== The function wci.addCodeLevelParameter allows an administrator to add new Level Parameters representing code tables to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addcodelevelparameter ( parameterName text, parameterReference text ) === Parameters === ^ Parameter ^ Description ^ | parameterName | The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code. | | parameterReference | Reference information for the code table. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'hybrid level' code parameter from WMO: SELECT wci.addcodelevelparameter ( 'hybrid level', 'WMO Code Table 3, WMO publication no. 306 - Manual on Code' ); === See Also === * wci.addmeasurelevelparameter * wci.getcodelevelparameter * wci.getlevelparameter * wci.getmeasurelevelparameter ==== wci.addCodeValueParameter ==== The function wci.addCodeValueParameter allows an administrator to add new Value Parameters representing code tables to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addcodevalueparameter ( parameterName text, parameterReference text ) === Parameters === ^ Parameter ^ Description ^ | parameterName | The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code. | | parameterReference | Reference information for the code table. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'yr weather symbol' code parameter from www.yr.no: SELECT wci.addcodevalueparameter ( 'yr weather symbol', 'http://www.yr.no' ); === See Also === * wci.addparameterfunctiontype * wci.getcodevalueparameter * wci.getvalueparameter * wci.getparameterfunctiontype ==== wci.addDataProvider ==== The function wci.addDataProvider allows an administrator to add a new Data Provider to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.adddataprovider ( dataProviderName text, dataProviderType text, domainDelivery text, dataProviderComment text ) === Parameters === ^ Parameter ^ Description ^ | dataProviderName | The canonical data provider name to be used (i.e., the data provider name set in the default name space. Ideally, this should be a universally unique name or code. | | dataProviderType | The type of the data provider. Currently, this may be one of the following: * Aeroplane * Computer System * Data Provider Group * Named Observation Site * Person * Ship * WCI User | | domainDelivery | The domain of the data delivered by the data provider. A precise domain definition helps the database to optimize the queries. The options are: * Any * Grid * Point | | dataprovidercomment | Supplementary information about the dataprovider. | \\ === Expected Result === The DataProviderId (key reference number). === Example === An example setting up the data provider "michael" who provides point data: SELECT wci.adddataprovider ( 'michael', 'Person', 'Point', 'Editor of point forecasts' ); Adding a new model to the database: SELECT wci.adddataprovider( 'longyear', 'Computer System', 'Grid', 'Model generated from longyearbyen' ); === See Also === * wci.adddataprovidertogroup * wci.addwciuser * wci.getdataprovider * wci.getdataprovidername * wci.setdataprovidername ==== wci.addDataProviderToGroup ==== The function wci.addDataProviderToGroup allows an administrator to add a specified data provider to a data provider group in WDB. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.adddataprovidertogroup ( dataProviderName text, dataProviderGroup text ) === Parameters === ^ Parameter ^ Description ^ | dataProviderName | The data provider name to be added to the specified group. | | dataProviderGroup | The data provider group that you want to add this data provider name to. | \\ === Expected Result === The DataProviderId (key reference number) of the assigned data provider. === Example === An example setting the data provider "michael" into group 'metno': SELECT wci.adddataprovidertogroup ( 'michael', 'metno' ); === See Also === * wci.adddataprovider * wci.addwciuser * wci.getdataprovider * wci.getdataprovidername * wci.setdataprovidername ==== wci.addDimensionlessValueParameter ==== The function wci.addDimensionlessValueParameter allows an administrator to add new Value Parameters without a physical dimension to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.adddimensionlessvalueparameter ( parameterName text, parameterDescription text ) === Parameters === ^ Parameter ^ Description ^ | parameterName | The canonical parameter name to be used for the measure table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or measure. | | parameterDescription | A description of the value parameter. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'land cover' value parameter from WMO: SELECT wci.adddimensionlessvalueparameter ( 'land cover', 'Proportion of grid cell covered by land (WMO)' ); === See Also === * wci.getvalueparameter ==== wci.addFunctionValueParameter ==== The function wci.addFunctionValueParameter allows an administrator to add new function value parameters to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addfunctionvalueparameter ( parameterUsage text, parameterUnit text, parameterFunction text, parameterQuantity text ) === Parameters === ^ Parameter ^ Description ^ | parameterUsage | The usage dimension of the value parameter. | | parameterUnit | The SI unit of the value parameter. The unit is used to determine the physical dimension of the function value parameter. | | parameterFunction | The function of the value parameter. | | parameterQuantity | The quantity type of the value parameter; either scalar or vector. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'mean wind waves duration' value parameter to the database: SELECT wci.addfunctionvalueparameter ( 'wind waves', 's', 'mean', 'scalar' ); === See Also === * wci.getvalueparameter ==== wci.addLevelParameterUsage ==== The function wci.addLevelParameterUsage allows an administrator to add new Level Parameter usages to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addlevelparameterusage ( levelParameterUsage text, levelDescription text ) === Parameters === ^ Parameter ^ Description ^ | levelParameterUsage | A usage dimension for a level parameter. | | levelDescription | A description of the usage dimensions. | \\ === Expected Result === None. === Example === An example adding the 'height above ground' level usage to the database: SELECT wci.addlevelparameterusage ( 'height above ground', 'Denotes the height level of the value-' ); === See Also === * wci.getlevelparameterusage ==== wci.addMeasure ==== The function wci.addMeasure allows an administrator to add new measures (e.g., physical dimensions) to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addmeasure ( measure character varying, distancepower integer, masspower integer, timepower integer, luminositypower integer, electriccurrentpower integer, temperaturepower integer, substanceamountpower integer, anglepower integer ) === Parameters === ^ Parameter ^ Description ^ | measure | The measure being described. | | distancepower | The distance dimension of the measure. Use 0 to denote none. | | masspower | The mass dimension of the measure. Use 0 to denote none. | | timepower | The time dimension of the measure. Use 0 to denote none. | | luminositypower | The luminosity dimension of the measure. Use 0 to denote none. | | electriccurrentpower | The electric current dimension of the measure. Use 0 to denote none. | | temperaturepower | The temperature dimension of the measure. Use 0 to denote none. | | substancepower | The substance dimension of the measure. Use 0 to denote none. | | anglepower | The angular dimension of the measure. Use 0 to denote none. | \\ === Expected Result === None. === Example === An example adding 'acceleration' measure to the database: SELECT wci.addmeasure ( 'acceleration', 1, 0, -2, 0, 0, 0, 0, 0 ); === See Also === * wci.getmeasure ==== wci.addMeasureLevelParameter ==== The function wci.addMeasureLevelParameter allows an administrator to add new level parameters based on measures to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addmeasurelevelparameter ( parameterUsage text, parameterUnit text ) === Parameters === ^ Parameter ^ Description ^ | parameterUsage | The usage dimension of the level parameter. | | parameterUnit | The SI unit of the level parameter. The unit is used to determine the physical dimension of the measure value parameter. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'isobaric surface pressure' level parameter to the database: SELECT wci.addmeasurelevelparameter ( 'isobaric surface', 'Pa' ); === See Also === * wci.getlevelparameter ==== wci.addMeasureValueParameter ==== The function wci.addMeasureValueParameter allows an administrator to add new value parameters based on measures to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addmeasurevalueparameter ( parameterUsage text, parameterUnit text, parameterQuantity text ) === Parameters === ^ Parameter ^ Description ^ | parameterUsage | The usage dimension of the value parameter. | | parameterUnit | The SI unit of the value parameter. The unit is used to determine the physical dimension of the measure value parameter. | | parameterQuantity | The quantity type of the value parameter. | \\ === Expected Result === The ParameterId (key reference number). === Example === An example adding the 'air temperature' value parameter to the database: SELECT wci.addmeasurevalueparameter ( 'air', 'K', 'scalar' ); === See Also === * wci.addmeasure * wci.getmeasurevalueparameter ==== wci.addParameterFunctionType ==== The function wci.addParameterFunctionType allows an administrator to add new function types to be used with value parameters to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addparameterfunctiontype ( parameterFunctionType text, parameterFunctionDescription text ) === Parameters === ^ Parameter ^ Description ^ | parameterFunctionType | The name of the function type being defined for value parameters. | | parameterFunctionDescription | A description of the parameter function. | \\ === Expected Result === None. === Example === An example adding the 'max' function type to the database: SELECT wci.addparameterfunctiontype ( 'max', 'Maximum value for the period specified by the valid time interval' ); === See Also === * wci.getfunctionvalueparameter ==== wci.addPlacePoint ==== The function wci.addPlacePoint allows an administrator to add a new place definition for a point to the WDB system. === Prerequisites === * The user must have write privileges on the database. === Syntax === wci.addplacepoint ( placeName text, placeGeometry text ) === Parameters === ^ Parameter ^ Description ^ | placeName | The name (in the defined namespace) of the Point to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space. | | placeGeometry | The point geometry to be inserted into the place definition tables. | \\ === Expected Result === The PlaceId (key reference number). === Example === An example setting up the place point "karasjok": SELECT wci.addplacepoint ( 'karasjok', geomfromtext('POINT( 25.51 69.47 )') ); Adding this point to the database while logged into a place name space other than zero, will add a point with the place name of 'karasjok' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database. === See Also === * wci.addplacepolygon * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.addPlacePolygon ==== The function wci.addPlacePolygon allows an administrator to add a new place definition for a polygon to the WDB system. === Prerequisites === * The user must have write privileges on the database. === Syntax === wci.addplacepolygon ( placeName text, placeGeometry text ) === Parameters === ^ Parameter ^ Description ^ | placeName | The name (in the defined namespace) of the Polygon to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space. | | placeGeometry | The point geometry to be inserted into the place definition tables. | \\ === Expected Result === The PlaceId (key reference number). === Example === An example setting up a polygon for "square at nowhere": SELECT wci.addplaceplygon ( 'square at nowhere', geomfromtext('POLYGON(() 10.0 61.3, 10.1 61.3, 10.1 61.4, 10.0 61.4, 10.0 61.3 ))') ); Adding this polygon to the database while logged into a place name space other than zero, will add a point with the place name of 'square at nowhere' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database. === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.addPlacerRegularGrid ==== The function wci.addPlaceRegularGrid allows an administrator to add a new place definition for a regular grid to the WDB system. === Prerequisites === * The user must have write privileges on the database. === Syntax === wci.addplaceregulargrid ( placeName text, numX int, numY int, incX float, incY float, startX float, startY float, projection text ) === Parameters === ^ Parameter ^ Description ^ | placeName | The name (in the defined namespace) of the grid to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space. | | numX | The number of points along the X axis of the grid. | | numY | The number of points along the Y axis of the grid. | | incX | The distance between any two points on the X axis of the grid. The unit of measure is given by the projection. | | incY | The distance between any two points on the Y axis of the grid. The unit of measure is given by the projection. | | startX | The origin X point (lower left corner) of the grid in the specified projection. | | startY | The origin Y point (lower left corner) of the grid in the specified projection. | | projection | The original projection of the grid, which also corresponds to the form it is stored as in the database.. | \\ === Expected Result === The PlaceId (key reference number). === Example === An example setting up the hirlam 10km grid: SELECT wci.addplaceregulargrid ( 'hirlam 10km grid', 248, 400, 0.100, 0.100, 5.75, -13.25, '+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs' ); Adding this grid to the database while logged into a place name space other than zero, will add a grid with the place name of 'hirlam 10km grid' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database. === See Also === * wci.addplacepoint * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.addSrid ==== The function wci.addSrid allows an administrator to add a new SRID definition to WDB. === Prerequisites === * The user must have write privileges on the database. === Syntax === wci.addsrid ( name text, projection text ) === Parameters === ^ Parameter ^ Description ^ | name | A descriptive name for the projection. | | projection | The Proj.4 definition of the projection. To avoid duplicates, the Proj.4 definition should avoid unnecessary spacing and be ended with +no_defs. It is advised to manually check the spatial_ref_sys table (using wci.getSrid) before adding new entries. | \\ === Expected Result === The SRID (spatial reference id). === Example === An example setting up the SRID of the Hirlam 10 grid (a rotated, longitude/latitude projection: SELECT wci.addsrid ( 'Hirlam 10 SRID', '+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs'); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.addUnit ==== The function wci.addUnit allows an administrator to add a new unit to WDB. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addunit ( unitname character varying, unittype character varying, measure character varying, description character varying, siunitconversioncoefficient double, siunitconversionterm double ) === Parameters === ^ Parameter ^ Description ^ | unitName | The UCUM designation of the unit. | | unitType | The type of the unit. Permitted types are: 'SI Unit', 'Base Unit', and 'Conventional Unit'. Most units should be defined as the latter. | | measure | The associated measure of the unit. | | description | A description of the unit. For most units, this will simply be the unabbreviated (i.e., full) form of the unit name. | | siunitconversioncoefficient | The coefficient to multiply the value with in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term | | siunitconversionterm | The term to add to the value in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term | \\ === Expected Result === None. === Example === An example adding the degree Fahrenheit to the database: SELECT wci.addunit( '[degF]', 'Conventional Unit', 'temperature', 'degree Fahrenheit', 0.555556, 459.67 ); An example adding the Kelvin to the database: SELECT wci.addunit( 'K', 'SI Unit', 'temperature', 'Kelvin', 1, 0 ); === See Also === * wci.addmeasure ==== wci.addValueParameterUsage ==== The function wci.addValueParameterUsage allows an administrator to add new Value Parameter usages to the WDB system. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addvalueparameterusage ( valueParameterUsage text, valueDescription text ) === Parameters === ^ Parameter ^ Description ^ | valueParameterUsage | A usage dimension for a value parameter. | | valueDescription | A description of the usage dimension. | \\ === Expected Result === None. === Example === An example adding the 'mean sea level' value usage to the database: SELECT wci.addvalueparameterusage ( 'mean sea level', 'Value reduced to sea level assuming an isothermal layer at the measuring point's temperature.' ); === See Also === * wci.getvalueparameterusage ==== wci.addWciUser ==== The function wci.addWciuser allows an administrator to add a WCI user to the database as a data provider in WDB. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.addwciuser ( dataProviderName text ) === Parameters === ^ Parameter ^ Description ^ | dataProviderName | The data provider name to be added to the database as a WCI user. | \\ === Expected Result === The DataProviderId (key reference number) of the inserted data provider. === Example === An example adding the wci user "michael" as a new data provider: SELECT wci.addwciuser( 'michael' ); === See Also === * wci.adddataprovider * wci.adddataprovidertogroup * wci.getdataprovider * wci.getdataprovidername * wci.setdataprovidername ==== wci.begin ==== The function wci.begin initializes the WDB Call Interface for a specified user. === Prerequisites === * The user must have been set up as a WDB user (i.e., have access to one of the wdb user groups === Syntax === wci.begin ( user name, dataproviderNameSpaceId integer, placeNameSpaceId integer, parameterNameSpaceId integer ) wci.begin ( user name ) === Parameters === ^ Parameter ^ Description ^ | user | The userid to initialize the connection with | | dataprovidernamespaceid | The namespace to be used for dataprovider names in the session | | placenamespaceid | The namespace to be used for place names in the session | | parameternamespaceid | The namespace to be used for parameter names in the session | \\ === Expected Result === No return expected. === Example === An example setting up the user "michael" with the data provider and parameter name spaces associated with the code 1, while retaining use of the default place names: SELECT wci.begin ( 'michael', 1, 0, 1 ); Note that the default namespaces can be defined by the WDB administrator. Consequently, the user may frequently want to just install using this namespace, which would be done with the following wci.begin call: SELECT wci.begin ( 'michael' ); === See Also === * wci.end ==== wci.browse ==== The wci.browse function is utilized to browse the meteorological, hydrological and oceanographic data in the database. Essentially, it can be used to retrieve summary data about what data values exist in the database. The function takes as input the same search parameters as the wci.read call, but returns summarized rather than detailed data about the values in the database. Using wci.browse will usually be significantly faster than performing a similar wci.read call followed by aggregation. The function is overloaded, and exists in many different versions, depending on the return type required. === Prerequisites === * The user must have access to group role wdb_read * The user must have called wci.begin === Syntax === wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browsedataprovider ) wci.browse ( returnType wci.browsedataprovider ) wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browseplace ) wci.browse ( returnType wci.browseplace ) wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browsereferencetime ) wci.browse ( returnType wci.browsereferencetime ) wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browsevalidtime ) wci.browse ( returnType wci.browsevalidtime ) wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browsevalueparameter ) wci.browse ( returnType wci.browsevalueparameter ) wci.browse ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.browselevelparameter ) wci.browse ( returnType wci.browselevelparameter ) === Parameters === All the wci.browse input parameters, except the returnType, are precisely the same as the input paramaters to a wci.read call (see Section Parameters). Calling a function with only the "returnType" parameter specified is basically equivalent to calling the wci.browse function with all NULLs (indicating that all data is required). Be aware that trying to retrieve aggregates about all the data in a huge database can take a while. The returnType specifies which of the six different types of summarized metadata the user wants to retrieve. === Expected Result === Depending on the returnType specified: * wci.browsedataprovider This returns a list of the data providers that exist in the database for the parameter definitions given in the wci.browse call and the utilized namespace. For each dataprovider, the number of data records and the earliest and latest referencetimes that exist for that data value is also listed. * wci.browseplace This returns a list of the place definitions that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each place definition, the number of data records in the database are listed. * wci.browsereferencetime This returns a list of the referencetimes that exist in the database for the parameter definitions given by the wci.browse call. For each referencetime, the number of data records in the database are listed. * wci.browsevalidtime This returns a list of the validtimes that exist in the database for the parameter definitions given by the wci.browse call. For each validtime, the number of data records in the database are listed. * wci.browsevalueparameter This returns a list of the value parameters that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each valueparameter, the number of data records in the database are listed. * wci.browselevelparameter This returns a list of the level parameters that exist in the database for the parameter definitions given by the wci.browse call and the utilized namespace. For each level parameter, the number of data records in the database are listed. === Example === The following browse query could be used to retrieve the data provider names of all data providers in the database. SELECT * FROM wci.browse ( NULL::wci.browsedataprovider ); The user might then utilize a result from this query to ask a follow-up determining the reference times of a specific data provider. SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ], NULL, NULL, NULL, NULL, NULL, NULL, NULL::wci.browsereferencetime ); The results from this query (a list of referencetimes), can then be used to drill down further into the data mass of the database. The following example retrieves the list of parameters for the given data provider and reference time. SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ], NULL, 'exact 1980-03-15 12:00:00+00', NULL, NULL, NULL, NULL, NULL::wci.browsevalueparameter ); === See Also === * wci.read ==== wci.configuration ==== The wci.configuration function returns all configuration information (i.e., the complete list of all versions installed) for the WDB database. === Prerequisites === * The user must have read access to the database. === Syntax === wci.configuration ( ) === Parameters === None. === Expected Result === Configuration information. ^ Attribute ^ Description ^ | name | The name of the software package. | | softwareversion | The version of the software. | | packageversion | The version of the package; this is a sequential number independent of the software version. | | description | A description of the software package. | | installtime | The time when this version of WDB was installed. | \\ === Example === An example to extract the configuration of the database: SELECT wci.configuration ( ); === See Also === * wci.version ==== wci.end ==== The function wci.end unsets any settings and frees up resources that may have been initialized by wci.begin. === Prerequisites === None. === Syntax === wci.end ( ) === Parameters === None. === Expected Result === No return expected. === Example === The wci.end function is just a simple functional call: SELECT wci.end ( ); === See Also === * wci.begin ==== wci.fetch ==== wci.fetch is the function used to retrieve binary data values from the database. The function takes a binary object ID returned by a wci.read call and returns a row containing the binary data (as bytea data) as well as additional relevant information required for the manipulation of the binary data. The returned binary data should be interpreted as 4-byte floats. Some of the data may have the value not-a-number. This means that that particular point does not have any defined value. === Prerequisites === * The user must have a valid object ID that references a grid * The user must have access to group role wdb_read * The user must have called wci.begin === Syntax === wci.fetch ( objectid bigint, returnType wci.grid ) === Parameters === ^ Parameter ^ Description ^ | objectid | The object ID of the binary object to be returned, as given by a wci.read call | | returnType | What type of data the user wants returned | \\ === Expected Result === Currently, the function always returns a: * wci.grid === Examples === The following query returns the grid referenced as 11702: SELECT * FROM wci.fetch ( 11702, NULL::wci.grid -- Return type ) The result is a single row containing the binary data of the grid itself (as a bytea), in addition to the number of points along the x and y axis of the grid, the distance between grid increments, the starting positions of the x and y points in the original projection, and the PROJ.4 string defining the original projection of the grid. === See Also === * wci.read * wci.write ==== wci.getCodeLevelParameter ==== The function wci.getCodeLevelParameter returns information about the specified level parameter of the code type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getcodelevelparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the level parameter in the namespace. **Table�4.23.�wci.getCodeLevelParameter return row** ^ Attribute ^ Description ^ | levelparameterid | The internal parameter ID used in WDB. | | levelcodeparametername | The canonical name of the level parameter. | | codeparameterreference | The reference information for the level code. | | parameternamespaceid | The parameter name space ID of the query. | | levelparametername | The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical level parameter name. | \\ === Example === An example to get information about code "hybrid level": SELECT wci.getcodelevelparameter ( 'hybrid level' ); To retrieve information about all code level parameters starting with "hybrid": SELECT wci.getcodelevelparameter ( 'hybrid%' ); === See Also === * wci.addcodelevelparameter ==== wci.getCodeValueParameter ==== The function wci.getCodeValueParameter returns information about the specified value parameter of the code type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getcodevalueparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the value parameter in the namespace. ^ Attribute ^ Description ^ | valueparameterid | The internal parameter ID used in WDB. | | valuecodeparametername | The canonical name of the value parameter. | | codeparameterreference | The reference information for the value code. | | parameternamespaceid | The parameter name space ID of the query. | | valueparametername | The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | \\ === Example === An example to get information about code "ice presence": SELECT wci.getcodevalueparameter ( 'ice presence' ); To retrieve information about all code value parameters starting with "ice": SELECT wci.getcodevalueparameter ( 'ice%' ); === See Also === * wci.addcodevalueparameter ==== wci.getDataProvider ==== The function wci.getDataProvider returns information about the specified data provider to a user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getdataprovider ( dataProviderName text ) === Parameters === ^ Parameter ^ Description ^ | dataProviderName | The data provider name to be added to be returned. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the Data Provider in the namespace. ^ Attribute ^ Description ^ | dataproviderid | The internal data provider ID used in WDB. | | dataprovidertype | The type classification of the data provider in WDB. | | spatialdomaindelivery | The spatial domain of data delivered by this data provider; either point data, gridded data, or both. | | dataprovidernamespaceid | The currently selected data provider name space. | | dataprovidername | The data provider name of the data provider in this namespace. | | dataprovidernameleftset | An internal WDB code used for grouping. | | dataprovidernamerightset | An internal WDB code used for grouping. | | dataproviderstoretime | The store time of this data provider; i.e., when it was inserted into the database. | | dataprovidercomment | Additional description or comment about the data provider. | \\ === Example === An example to get information about data provider "michael": SELECT wci.getdataprovider ( 'michael' ); To retrieve information about all data providers starting with "mich": SELECT wci.getdataprovider ( 'mich%' ); === See Also === * wci.adddataprovider * wci.adddataprovider2group * wci.addwciuser * wci.getdataprovidername * wci.setdataprovidername ==== wci.getDataProviderName ==== The function wci.getDataProviderName lists the data provider names in the namespace that match the search criteria. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getdataprovidername ( dataprovidername text ) === Parameters === ^ Parameter ^ Description ^ | dataProviderName | The data provider name for which information is requested. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of data provider names. ^ Attribute ^ Description ^ | dataproviderid | The internal data provider ID used in WDB. | | dataprovidernamespaceid | The currently selected data provider name space. | | dataprovidername | The data provider name of the data provider in this namespace. | \\ === Example === An example to list the data provider matching the name "michael": SELECT wci.getdataprovidername ( 'michael' ); List all data providers starting on "mich" in the name space: SELECT wci.getdataprovidername ( 'mich%' ); === See Also === * wci.adddataprovider * wci.adddataprovider2group * wci.addwciuser * wci.getdataprovider * wci.setdataprovidername ==== wci.getDimensionlessValueParameter ==== The function wci.getDimensionlessValueParameter returns information about the specified value parameter of the dimensionless type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getdimensionlessvalueparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the value parameter in the namespace. ^ Attribute ^ Description ^ | valueparameterid | The internal parameter ID used in WDB. | | valuedimensionlessparametername | The canonical name of the value parameter. | | valueparameterdescription | A description of the value parameter. | | valueunitname | The unit of the value parameter. | | parameternamespaceid | The parameter name space ID of the query. | | valueparametername | The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | \\ === Example === An example to get information about the parameter "land albedo": SELECT wci.getdimensionlessvalueparameter ( 'land albedo' ); To retrieve information about all code value parameters starting with "land": SELECT wci.getdimensionlessvalueparameter ( 'land%' ); === See Also === * wci.adddimensionlessvalueparameter ==== wci.getFunctionValueParameter ==== The function wci.getFunctionValueParameter returns information about the specified value parameter of the function type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getfunctionvalueparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the value parameter in the namespace. ^ Attribute ^ Description ^ | valueparameterid | The internal parameter ID used in WDB. | | parameterfunctiontype | The parameter function. | | valueparameterusage | The value parameter usage. | | parameterquantitytype | The quantity type of the value parameter. | | measure | The measure of the value parameter. | | valueunitname | The unit name used for the value parameter. | | parameternamespaceid | The parameter name space ID of the query. | | valueparametername | The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | \\ === Example === An example to get information about the parameter "peak wave duration": SELECT wci.getfunctionvalueparameter ( 'peak wave duration' ); To retrieve information about all value parameters starting with "peak": SELECT wci.getfunctionvalueparameter ( 'peak%' ); === See Also === * wci.addfunctionvalueparameter ==== wci.getLevelParameter ==== The function wci.getLevelParameter returns information about the specified level parameter of the function type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getlevelparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the level parameters in the namespace. ^ Attribute ^ Description ^ | levelparameterid | The internal parameter ID used in WDB. | | parameternamespaceid | The parameter name space ID of the query. | | levelparametername | The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | | levelunitname | The unit of the level parameter. | \\ === Example === An example to get information about the level parameter "hybrid level": SELECT wci.getlevelparameter ( 'hybrid level' ); To retrieve information about all level parameters with "hybrid": SELECT wci.getlevelparameter ( '%hybrid%' ); === See Also === * wci.addcodelevelparameter * wci.addmeasurelevelparameter ==== wci.getlevelparameterusage ==== The function wci.getlevelparameterusage returns information about the specified level parameter usage to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getlevelparameterusage ( usage text ) === Parameters === ^ Parameter ^ Description ^ | usage | The name of the parameter usage to be returned. NULL returns all parameter usages. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the level parameter usages. ^ Attribute ^ Description ^ | levelparameterusage | The level parameter usage descriptor. | | levelparameterusagedescription | A description of the level parameter usage. | \\ === Example === An example to get information about the level usage "sea surface": SELECT wci.getlevelparameterusage ( 'sea surface' ); To retrieve information about all level usages with "sea": SELECT wci.getlevelparameterusage ( '%sea%' ); === See Also === * wci.addlevelparameterusage ==== wci.getMeasure ==== The function wci.getMeasure returns information about the specified measure to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getmeasure ( measure text ) === Parameters === ^ Parameter ^ Description ^ | measure | The name of the measure to be returned. NULL returns all measures. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the measure. ^ Attribute ^ Description ^ | measure | The measure being described. | | distancepower | The distance dimension of the measure. Use 0 to denote none. | | masspower | The mass dimension of the measure. Use 0 to denote none. | | timepower | The time dimension of the measure. Use 0 to denote none. | | luminositypower | The luminosity dimension of the measure. Use 0 to denote none. | | electriccurrentpower | The electric current dimension of the measure. Use 0 to denote none. | | temperaturepower | The temperature dimension of the measure. Use 0 to denote none. | | substancepower | The substance dimension of the measure. Use 0 to denote none. | | anglepower | The angular dimension of the measure. Use 0 to denote none. | \\ === Example === An example to get information about the measure "distance": SELECT wci.getmeasure ( 'distance' ); === See Also === * wci.addmeasure ==== wci.getMeasureLevelParameter ==== The function wci.getmeasurelevelParameter returns information about the specified level parameter of the function type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getmeasurelevelparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the level parameters in the namespace. ^ Attribute ^ Description ^ | levelparameterid | The internal parameter ID used in WDB. | | levelparameterusage | The usage of the level parameter. | | measure | The measure of the level parameter. | | levelunitname | The unit of the level parameter. | | parameternamespaceid | The parameter name space ID of the query. | | levelparametername | The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | \\ === Example === An example to get information about the level parameter "sea surface pressure": SELECT wci.getmeasurelevelparameter ( 'sea surface pressure' ); To retrieve information about all level parameters with "sea": SELECT wci.getmeasurelevelparameter ( '%sea%' ); === See Also === * wci.addmeasurelevelparameter ==== wci.getMeasureValueParameter ==== The function wci.getmeasurevalueParameter returns information about the specified value parameter of the function type to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getmeasurevalueparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the value parameters in the namespace. ^ Attribute ^ Description ^ | valueparameterid | The internal parameter ID used in WDB. | | valueparameterusage | The usage of the value parameter. | | parameterquantitytype | The quantity type of the value parameter. | | measure | The measure of the value parameter. | | valueunitname | The unit of the value parameter. | | parameternamespaceid | The parameter name space ID of the query. | | valueparametername | The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name. | \\ === Example === An example to get information about the value parameter "air temperature": SELECT wci.getmeasurevalueparameter ( 'air temperature' ); To retrieve information about all temperature parameters: SELECT wci.getmeasurevalueparameter ( '%temperature%' ); === See Also === * wci.addmeasurevalueparameter ==== wci.getParameterFunctionType ==== The function wci.getparameterfunctiontype returns information about the specified parameterfunctiontype to the user. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getparameterfunctiontype ( type text ) === Parameters === ^ Parameter ^ Description ^ | type | The name of the parameterfunctiontype to be returned. NULL returns all types. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === A row of data describing the parameterfunctiontype. ^ Attribute ^ Description ^ | parameterfunctiontype | The parameterfunctiontype being described. | | parameterfunctiondescription | A description of the parameter function type. | \\ === Example === An example to get information about the parameterfunctiontype "accumulated": SELECT wci.getparameterfunctiontype ( 'accumulated' ); === See Also === * wci.addparameterfunctiontype ==== wci.getPlaceDefinition ==== The function wci.getPlaceDefinition lists the place definitions defined in the database that match the search criteria and are available in the namespace. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getplacedefinition ( placename text ) === Parameters === ^ Parameter ^ Description ^ | placename | The placename that you require information for. NULL returns all place definitions in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of place definitions. ^ Attribute ^ Description ^ | placeid | The internal place ID used in WDB. | | placegeometrytype | The place geometry of the place definition. Currently points and grids are supported | | placegeometry | The geometry of the place definition in the default SRID. Note that for regular grids, only a polygon of the four corner points is stored in this field. | | placeindeterminatecode | The indeterminate code for the place definition. | | placenamespaceid | The name space of the query. | | placename | The place name of the place definition. | | originalsrid | The original SRID of the place definition. This is particularly important to keep track of for grids. | | placestoretime | The storetime of the place definition. | \\ === Example === An example to list the place definitions matching the name "oslo": SELECT wci.getplacedefinition ( 'oslo' ); List all place definitions starting on "os" in the name space: SELECT wci.getplacedefinition ( 'os%' ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.getPlaceName ==== The function wci.getPlaceName lists the place names defined in the database that match the search criteria and are available in the namespace. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getplacename ( placename text ) wci.getplacename ( numberX int, numberY int, incrementX float, incrementY float, startX float, startY float, projdefinition text ) === Parameters === ^ Parameter ^ Description ^ | placename | The placename that you require information for. NULL returns all place names in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | | numberx | The number of points along the x axis in the regular grid. | | numbery | The number of points along the y axis in the regular grid. | | incrementx | The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters. | | incrementy | The increment distance on the y axis. | | startx | The starting point of the grid on the x axis of the original Proj.4 projection. | | starty | The starting point of the grid on the y axis of the original Proj.4 projection. | | projdefinition | The original PROJ.4 projection of the place definition. | \\ === Expected Result === The list of place grids. ^ Attribute ^ Description ^ | placeid | The internal place ID used in WDB. | | placenamespaceid | The name space of the query. | | placename | The place name of the place definition. | \\ === Example === An example to list the placenames matching "osl": SELECT wci.getplacename ( 'osl%' ); List the place grid matching a set of attributes: SELECT wci.getplacename ( 248, 400, 0.5, 0.5, 35.6, -25.4, "+proj=longlat +a=6367470.0 +towgs84=0,0,0 +no_defs" ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacepoint * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.getPlacePoint ==== The function wci.getPlacePoint lists all the place points defined in the database that match the search criteria and are available in the namespace. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getplacepoint ( placename text ) === Parameters === ^ Parameter ^ Description ^ | placename | The placename that you require information for. NULL returns all place points in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of place points. ^ Attribute ^ Description ^ | placeid | The internal place ID used in WDB. | | placegeometrytype | The place geometry of the place point. Currently points and grids are supported | | placegeometry | The geometry of the place point. | | placeindeterminatecode | The indeterminate code for the place point. | | placenamespaceid | The name space of the query. | | placename | The place name of the place point. | | originalsrid | The original SRID of the place point. | | placestoretime | The storetime of the place point. | \\ === Example === An example to list the place points matching the name "oslo": SELECT wci.getplacepoint ( 'oslo' ); List all place points starting on "os" in the name space: SELECT wci.getplacepoint ( 'os%' ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplaceregulargrid * wci.getsrid * wci.setplacename ==== wci.getPlaceRegularGrid ==== The function wci.getPlaceRegularGrid lists the place grids defined in the database that match the search criteria and are available in the namespace. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getplaceregulargrid ( placename text ) === Parameters === ^ Parameter ^ Description ^ | placename | The placename that you require information for. NULL returns all place grids in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of place grids. ^ Attribute ^ Description ^ | placeid | The internal place ID used in WDB. | | placegeometrytype | The place geometry of the place definition. Currently points and grids are supported | | placegeometry | The geometry of the place definition. | | placeindeterminatecode | The indeterminate code for the place definition. | | placenamespaceid | The name space of the query. | | placename | The place name of the place definition. | | numberx | The number of points along the x axis in the regular grid. | | numbery | The number of points along the y axis in the regular grid. | | incrementx | The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters. | | incrementy | The increment distance on the y axis. | | startx | The starting point of the grid on the x axis of the original Proj.4 projection. | | starty | The starting point of the grid on the y axis of the original Proj.4 projection. | | originalsrid | The original SRID of the place definition. This is particularly important to keep track of for grids. | | projdefinition | The original PROJ.4 projection of the place definition. | | placestoretime | The storage time of the place definition. | \\ === Example === An example to list the place grid matching the name "hirlam 10 grid": SELECT wci.getplaceregulargrid ( 'hirlam 10 grid' ); List all place grid starting on "hirlam" in the name space: SELECT wci.getplaceregulargrid ( 'hirlam%' ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getsrid * wci.setplacename ==== wci.getSrid ==== The function wci.getSrid lists all the spatial reference ID's defined in the database that match the search criteria and are available in the namespace. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getsrid ( projstr text ) === Parameters === ^ Parameter ^ Description ^ | projstr | The Proj.4 string that matches the SRID you want to retrieve. NULL returns all SRIDs in the spatial reference system table. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of SRIDs. ^ Attribute ^ Description ^ | srid | The spatial reference ID. An integer value that uniquely identifies the Spatial Referencing System (SRS) within the database. | | auth_name | The name of the standard or standards body that is being cited for this reference system. For example, "EPSG" would be a valid auth_name. | | auth_srid | he ID of the Spatial Reference System as defined by the Authority cited in the auth_name. For EPSG data, for example, this is the EPSD id number. | | srtext | The Well-Known Text representation of the Spatial Reference System. WDB ignores this column and always inserts NULL. | | proj4text | This is the Proj.4 coordinate definition string for a particular SRID. | \\ === Example === An example to list the SRID's with longitude/latitude projections: SELECT wci.getsrid ( '%+proj=longlat%' ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplaceregulargrid * wci.addsrid * wci.setplacename ==== wci.getunit ==== The function wci.getunit lists all the units defined in the database that match the search criteria. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getunit ( unit text ) === Parameters === ^ Parameter ^ Description ^ | unit | The UCUM designation of the unit. NULL returns all units in the database. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of units. ^ Attribute ^ Description ^ | unitname | The name (context-sensitive UCUM designation) of the unit. | | unittype | The type of the unit. | | measure | The measure of the unit, if any. | | description | A description of the unit. | | siunitconversioncoefficient | The coefficient to multiply the value with to get the SI unit (if any). The formula is (value * coefficient) + term | | siunitconversionterm | The term to add to the value to get the SI unit (if any). The formula is (value * coefficient) + term | \\ === Example === An example to list all units with pressure (Pascal): SELECT wci.getunit ( '%Pa%' ); === See Also === * wci.addunit ==== wci.getValueParameter ==== The function wci.getValueParameter lists all the value parameters defined in the database that match the search criteria. === Prerequisites === * The user must have read access to the database. === Syntax === wci.getvalueparameter ( parameter text ) === Parameters === ^ Parameter ^ Description ^ | parameter | The name of the value parameter in the name space. NULL returns all value parameters in the name space. PostgreSQL wild cards (used in LIKE statements) may be used. | \\ === Expected Result === The list of valueparameters. ^ Attribute ^ Description ^ | valueparameterid | The internal parameter ID of the value parameter. | | parameternamespaceid | The currently selected parameter name space. | | valueparametername | The name of the valueparameter in the name space. | | valueparameterunit | The unit of measure of the value parameter. | \\ === Example === An example to list all value parameters based on temperature: SELECT wci.getvalueparameter ( '%temperature%' ); === See Also === * wci.addvalueparameter ==== wci.read ==== wci.read is the function that fetches MHO data from the database, and as such is the core of the WDB Call Interface. The function takes the user's search parameters as input and returns data as either individual point, or as a reference to a complete data grid (a Grid ID - shortened as GId). The function is overloaded, and exists in two almost identical versions, depending on the return type required. === Prerequisites === * The user must have access to group role wdb_read * The user must have called wci.begin === Syntax === wci.read ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.returnfloat ) wci.read ( dataProviders ARRAY[text], place text, referenceTime text, validtime text, parameters ARRAY[text], level text, dataVersions ARRAY[integer], returnType wci.returngid ) === Parameters === ^ Parameter ^ Description ^ | dataProviders | List of data providers for the MHO data to be retrieved | | place | A text string containing either a geometry describing the geographic locations that the user is interested in retrieving data for (formatted using well-known-text) or a placename. The string may optionally be prefixed with a place interpolation description. | | referenceTime | When the MHO data was created | | validtime | What time is the MHO data valid for | | parameters | What MHO-parameters the user is interested in retrieving | | level | What level (altitude/depth) the data is located at | | dataVersion | What version of the data should be returned | | returnType | What type of data the user wants returned | \\ Geospatial definitions are defined using well-known-text. Only POINTs and POLYGONs are currently supported. === Expected Result === Depending on the returnType specified: * wci.returnfloat * wci.returngid === Examples === The following query returns Hirlam 8 data from the database using a wci.read: SELECT * FROM wci.READ ( ARRAY['Hirlam norway'], -- Data provider name 'POINT(10 60)', -- Geometry '1980-04-05 12:00:00', -- Reference time 'inside 1980-04-06 00:00:00 TO 1980-04-07 00:00:00', --Valid time ARRAY['air pressure', 'air temperature'], -- Parameter NULL, -- Level ARRAY[-1], -- Data version NULL::wci.returnFloat -- Return type ) The above query returns Hirlam 8 data pressure and temperature data for the point closest to 10 degrees East, 60 degrees North that is valid for the twenty four hour time period of the 6th of April, 1980 and which was created (has the reference time) for the 5th of April, 12:00. The query returns all data that fulfills the above qualifications regardless of level, but only the latest version (dataversion) of the data available. Values will be returned as point data. === See Also === * wci.begin * wci.end * wci.fetch * wci.write ==== wci.setDataProviderName ==== The function wci.setDataProviderName allows an administrator to set the data provider name of a data provider in the currently selected namespace of WDB. If another data provider name has already been set for the data provider in the namespace, this function will overwrite the old name. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.setdataprovidername ( fromNameSpaceId int, fromName text, dataProviderName text ) === Parameters === ^ Parameter ^ Description ^ | fromNameSpaceId | The nameSpace Id of the fromName. | | fromName | The name of the data provider to insert a name for. The name is taken from the fromNameSpaceId. | | dataProviderName | The data provider name to be set. | \\ === Expected Result === No return. === Example === To rename the data provider with the canonical name "michael" to "michel", we would use: SELECT wci.setdataprovidername( 'michael', 'michel' ); === See Also === * wci.adddataprovider * wci.adddataprovidertogroup * wci.addwciuser * wci.getdataprovider * wci.getdataprovidername ==== wci.setLevelParameterName ==== The function wci.setLevelParameterName allows an administrator to set the name of a level parameter in the currently selected namespace of WDB. If another level parameter name has already been set in the namespace, this function will overwrite the old name. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.setlevelparametername ( canonicalName text, levelParameterName text ) === Parameters === ^ Parameter ^ Description ^ | canonicalName | The name of the level parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function. | | levelParameterName | The level parameter name to be set. | \\ === Expected Result === No return. === Example === To rename the parameter with the canonical name "hybrid level" to "HL", we would use: SELECT wci.setlevelparametername( 'hybrid level', 'HL' ); === See Also === * wci.addcodelevelparameter * wci.addmeasurelevelparameter * wci.getlevelparameter ==== wci.setPlaceName ==== The function wci.setPlaceName allows an administrator to set the place name of a place definition in the currently selected namespace of WDB. If another place name has already been set for the place definition in the namespace, this function will overwrite the old name. === Prerequisites === * The user must have administrative access to the database. === Syntax === wci.setPlaceName ( canonicalName text, placeName text ) === Parameters === ^ Parameter ^ Description ^ | canonicalName | The canonical name of the place definition that you wish to change the place name for. | | placeName | The new place name of the place definition. | \\ === Expected Result === None. === Example === An example to set the name of the Hirlam 10 grid in the database: SELECT wci.setplacename ( 'grid(5.75 -13.25, 0.1 0.1, 248 400, 50001)', 'hirlam 10km grid' ); === See Also === * wci.addplacepoint * wci.addplaceregulargrid * wci.addsrid * wci.getplacedefinition * wci.getplacename * wci.getplacepoint * wci.getplaceregulargrid ==== wci.setValueParameterName ==== The function wci.setValueParameterName allows an administrator to set the name of a value parameter in the currently selected namespace of WDB. If another value parameter name has already been set in the namespace, this function will overwrite the old name. === Prerequisites === * The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group. === Syntax === wci.setvalueparametername ( canonicalName text, valueParameterName text ) === Parameters === ^ Parameter ^ Description ^ | canonicalName | The name of the value parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function. | | valueParameterName | The value parameter name to be set. | \\ === Expected Result === No return. === Example === To rename the parameter with the canonical name "air temperature" to "2TM", we would use: SELECT wci.setvalueparametername( 'air temperature', '2TM' ); === See Also === * wci.addcodevalueparameter * wci.adddimensionlessvalueparameter * wci.addfunctionvalueparameter * wci.addmeasurevalueparameter * wci.getvalueparameter ==== wci.version ==== wci.version is a simple function that permits the user to retrieve version information about the WDB system. === Prerequisites === * The user must have access to group role wdb_read === Syntax === wci.version ( ) === Parameters === None. === Expected Result === The function returns a text with a string that describes the version of the WDB system in the PostgreSQL database. === Examples === The following query returns the WDB version: SELECT wci.version ( ) The result is a single row of the text type containing the WDB version string. === See Also === * wci.begin ==== wci.write ==== wci.write is function that can be utilized to write MHO data into the database. The function is overloaded, and exists in several different versions depending on the input utilized. === Prerequisites === * The user must be connected to the database * The user must have access to group role wdb_write * The user must have called wci.begin === Syntax === wci.write ( value gid, placename text, referencetime timestamp without time zone, validtimerom timestamp without time zone, validtimeto timestamp without time zone valueparameter text, levelparameter text, levelFrom float, levelTo float ) wci.write ( value gid, placename text, referencetime timestamp without time zone, validtimerom timestamp without time zone, validtimeto timestamp without time zone valueparameter text, levelparameter text, levelFrom float, levelTo float ) wci.write ( row wci.returnGid ) === Parameters === ^ Parameter ^ Description ^ | value | The OID value to be retrieved | | placename | A text string identifying the geographical location that the data is being inserted for | | referenceTime | When the MHO data was created | | validtimefrom | What time is the MHO data valid for; starting time | | validtimefrom | What time is the MHO data valid for; ending time | | valueparameter | What MHO-parameters the user is interested in retrieving | | levelparameter | The parameter that describes the level designation | | levelFrom | What level (altitude/depth) the data is located at; starting point | | levelTo | What level (altitude/depth) the data is located at; ending point | | row | A wci.returnOid row. This function allows the user to take the result a query and write the same (or a slightly modified row) easily into the database. | \\ === Expected Result === The valueid of the inserted row. === See Also === * wci.read * wci.begin * wci.end ===== Data Type Reference ===== This section provides an overview of the data types that are returned from the database through WCI; in particular the return rows used by the wci.read and wci.write calls. ==== wci.browsedataprovider ==== The wci.browsedataprovider data type is a simple row type used to return summarized information about the data providers of the rows currently stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | dataprovidername | The name of the data provider that the summary information is about. | | 1 | referencetimefrom | The earliest referencetime in the database for the dataprovider for which there exists data. | | 2 | referencetimeto | The latest referencetime in the database for the dataprovider for which there exists data. | | 3 | numberoftuples | The number of data rows that exist in the database for the given dataprovider. | \\ ==== wci.browseplace ==== The wci.browseplace data type is a simple row type used to return summarized information about the placenames of the rows currently stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | placename | The name of the placedefinition that the summary information is about. | | 1 | referencetimefrom | The earliest referencetime in the database for the placename for which there exists data. | | 2 | referencetimeto | The latest referencetime in the database for the placename for which there exists data. | | 3 | numberoftuples | The number of data rows that exist in the database for the given placename. | \\ ==== wci.browsereferencetime ==== The wci.browsereferencetime data type is a simple row type used to return summarized information about the referencetime of the rows currently stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | referencetime | The reference time that the summary information is about. | | 1 | numberoftuples | The number of data rows that exist in the database for the given referencetime. | \\ ==== wci.browsevalidtime ==== The wci.browsevalidtime data type is a simple row type used to return summarized information about the validtime of the rows currently stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | validtimefrom | The start time of the validtime period that is being summarized. | | 1 | validtimeto | The end time of the validtime period being summarized. | | 2 | numberoftuples | The number of data rows that exist in the database for the given validtime period or time point . | \\ ==== wci.browsevalueparameter ==== The wci.browsevalueparameter data type is a simple row type used to return summarized information about the valueparameters currently used by the rows in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | valueparametername | The name of the valueparameter that the summary information is about. | | 1 | valueunitname | The unit of the parameter in the database. | | 2 | numberoftuples | The number of data rows that exist in the database of the given valueparameter. | \\ ==== wci.browselevelparameter ==== The wci.browselevelparameter data type is a simple row type used to return summarized information about the levelparameters and level values currently stored by the rows in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | levelparametername | The name of the levelparameter that the summary information is about. | | 1 | levelunitname | The unit of the parameter in the database. | | 2 | levelfrom | The level from value of the rows in the database. | | 3 | levelto | The level to value of the rows in the database. | | 4 | numberoftuples | The number of data rows that exist in the database of the given level parameter and level value combination. | \\ ==== wci.infodataprovider ==== The wci.infodataprovider data type is a simple row type used to return metadata information about the dataproviders that can be stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | dataprovidername | The name of the dataprovider. | | 1 | dataprovidertype | The type of the dataprovider. This specifies whether the dataprovider is a person, computer system, meteorological station, or something else. It can also specify that the dataprovidername represents a group of other dataproviders. | | 2 | spatialdomaindelivery | The spatialdomaindelivery describes the spatial domain in which the dataprovider returns data. Examples are points and grids. The spatialdomaindelivery //any// is used to indicate that the dataprovider can store and return data in several formats on the database. | | 3 | dataprovidercomment | A text field that provides additional descriptive information about the dataprovider. | | 4 | dataproviderstoretime | Describes the time at which the dataprovider information was created. | \\ ==== wci.infoplace ==== The wci.infoplace data type is a simple row type used to return metadata information about the place definitions that can be stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | placename | The name of the place definition. | | 1 | placegeometry | The geometry (in WKT) that describes the place definition. For regular grids, this is a polygon of the four corners of the grid transformed into the default projection of the database. | | 2 | placeindeterminatetype | The place indeterminate type is used to describe imprecision or missing data in the place definition information. | | 3 | placegeometrytype | The placegeometrytype describes what type of geometry the row describes. | | 4 | placestoretime | Describes the time at which the place definition was created. | \\ ==== wci.inforegulargrid ==== The wci.inforegulargrid data type is a simple row type used to return detailed metadata information about the place definitions of the grid type that can be stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | placename | The name of the place definition. | | 1 | numberX | The number of points along the X axis of the grid (i.e., the width). | | 2 | numberY | The number of points along the Y axis of the grid (i.e., the height). | | 3 | incrementX | The distance between two points on the X axis of the grid in the original projection of the grid. | | 4 | incrementY | The distance between two points on the Y axis of the grid in the original projection of the grid. | | 5 | startX | The starting point (lower left corner) of the grid on the X axis in the original projection of the grid. | | 6 | startY | The starting point (lower left corner) of the grid on the Y axis in the original projection of the grid. | | 7 | projDefinition | The proj.4 string that defines the original projection of the grid. Since the structure of a grid is not reprojected, this information maya be useful if you need to deal with the grid information directly. | \\ ==== wci.infovalueparameter ==== The wci.infovalueparameter data type is a simple row type used to return metadata information about the value parameters that can be stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | valueparametername | The name of the value parameter. | | 1 | valueunitname | The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible. | \\ ==== wci.infolevelparameter ==== The wci.infolevelparameter data type is a simple row type used to return metadata information about the level parameters that can be stored in the database. The following table describes the attributes. ^ Order ^ Attribute ^ Description ^ | 0 | levelparametername | The name of the level parameter. | | 1 | levelunitname | The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible. | \\ ==== wci.returnFloat ==== The wci.returnFloat data type is a simple row type used for returning floating-point data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnFloat; including the ordering of the attributes in the type. ^ Order ^ Attribute ^ Description ^ | 0 | value | The floating point value returned by the query | | 1 | data provider name | The name of the data provider of the value (as defined within the dataprovidernamespace selected) | | 2 | place name | The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed. | | 3 | place geometry | The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84. | | 4 | referencetime | The time of reference for the value returned | | 5 | validtime from | The first point in time for which the value is valid | | 6 | validtime to | The last point in time for which the value is valid | | 7 | validtime indeterminate code | The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe //exact//, which implies that the validtime interval given is precise. | | 8 | value parameter name | The parameter name for the value returned (as defined within the parameter name space selected) | | 9 | value parameter unit | The measurement unit for the value returned | | 10 | level parameter name | The parameter name for the level of the value returned (as defined within the parameter name space selected) | | 11 | level unit name | The measurement unit for the level of the value returned | | 12 | level from | The lower value of the level | | 13 | level to | The upper value of the level | | 14 | level indeterminate code | The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe //exact//. | | 15 | data version | The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members). | | 16 | confidence code | Quality marker (not currently used) | | 17 | value store time | The time when the data was inserted into the database | | 18 | value id | The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value | | 19 | value type | The type of the value returned. Together with the valueid, this constitutes a key of the WDB value | \\ ==== wci.returnGid ==== The wci.returnGid data type is a simple row type used for returning data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnGid; including the ordering of the attributes in the type. ^ Order ^ Attribute ^ Description ^ | 0 | value | The grid ID (GID) of the value being returned | | 1 | data provider name | The name of the data provider of the value (as defined within the dataprovidernamespace selected) | | 2 | place name | The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed | | 3 | place geometry | The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84. | | 4 | referencetime | The time of reference for the value returned | | 5 | validtime from | The first point in time for which the value is valid | | 6 | validtime to | The last point in time for which the value is valid | | 7 | validtime indeterminate code | The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe //exact//, which implies that the validtime interval given is precise. | | 8 | value parameter name | The parameter name for the value returned (as defined within the parameter name space selected) | | 9 | value parameter unit | The measurement unit for the value returned | | 10 | level parameter name | The parameter name for the level of the value returned (as defined within the parameter name space selected) | | 11 | level unit name | The measurement unit for the level of the value returned | | 12 | level from | The lower value of the level | | 13 | level to | The upper value of the level | | 14 | level indeterminate code | The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe //exact//. | | 15 | data version | The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members). | | 16 | confidence code | Quality marker (not currently used) | | 17 | value store time | The time when the data was inserted into the database | | 18 | value id | The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value | | 19 | value type | The type of the value returned. Together with the valueid, this constitutes a key of the WDB value | \\ ===== Examples ===== You can find a number of examples using SQL, perl, java, R-script and C++ in the source package of WDB, under the examples directory. ===== Frequently Asked Questions ===== This section is for a list of frequently asked questions about WCI. ===== Known Problems, Bugs, and Limitations ===== The following page describes some of the known problems and limitations of the WCI interface, and how to deal with them. === Limit of 100,000 rows returned by wci.read from a single grid === The wci.read function is limited to returning no more than 100,000 rows from a single grid operation. If you need to retrieve a greater number of values from one grid in the database, you should use wci.fetch to retrieve the Grid object directly and perform the retrieval manually.