http://docs.openlinksw.com/virtuoso/sqlreference.html SQL Reference OpenLink Virtuoso Universal Server: Documentation virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com 2008-09-09T11:44:52Z OpenLink Software Documentation Team http://docs.openlinksw.com/virtuoso/../images/misc/logo.jpg http://docs.openlinksw.com/virtuoso/sqlrefDATATYPES.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Datatypes 2008-09-09T11:44:52Z Datatypes http://docs.openlinksw.com/virtuoso/udt.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com User Defined Types 2008-09-09T11:44:52Z User Defined Types A user-defined type is a schema object, identified by a user-defined type name. The definition of a user-defined type specifies a number of components, including in particular a list of attribute definitions. The representation of a user-defined type is expressed as a list of attribute definitions. The definition of a user-defined type may include a method specification list consisting of one or more method specifications. A method specification is either an original method specification or an overriding method specification. Each original method specification specifies the method name, the SQL parameter declaration list, the returns data type, the <language clause>, the language (if the language is not SQL), and whether it is a STATIC or CONSTRUCTOR method. Each overriding method specification specifies the method name, the SQL parameter declaration list and the RETURNS data type. For each overriding method specification, there must be an original method specification with the same method name and SQL parameter declaration list in some proper supertype of the user-defined type. Every SQL-invoked method in a schema must correspond to exactly one original method specification or overriding method specification associated with some user-defined type existing in that schema. A method M that corresponds to an original method specification in the definition of a structured type T1 is an original method of T1. A method M that corresponds to an overriding method specification in the definition of T1 is an overriding method of T1. A method M is a method of type T1 if one of the following holds: http://docs.openlinksw.com/virtuoso/sqlrefxmldatatype.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com XML Column Type 2008-09-09T11:44:52Z XML Column Type Virtuoso allows for native XML storage in a database table column using the LONG XML type. This data type is a variation of LONG VARCHAR that can have plain text or XML entities, persistent or non-persistent values, but will always return an XML entity when selected. Since ODBC does not support an XML entity type this column will appear as a LONG VARCHAR when selected from ODBC based clients. http://docs.openlinksw.com/virtuoso/catidentifiers.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Identifier Case & Quoting 2008-09-09T11:44:52Z Identifier Case & Quoting Virtuoso can operate with different identifier case conventions. The CaseMode setting in the virtuoso.ini file controls this, see the virtuoso.ini configuration section of the documentation. The default files supplied with Virtuoso specify a CaseMode of 2, which is a case insensitive mode that preserves the declaration case of identifiers. A CaseMode of 1 specifies the upper case mode, which is most commonly used in SQL databases, e.g. Oracle. In the upper case mode, all unquoted identifiers are converted to upper case by the SQL parser. If identifiers are not quoted, the case in which they are entered is irrelevant. http://docs.openlinksw.com/virtuoso/wideidentifiers.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Wide Character Identifiers 2008-09-09T11:44:52Z Wide Character Identifiers All Virtuoso schema columns are confined to 8-bit character fields. This will remain for backwards compatibility and performance reasons, however, there are two options available for support of non-ASCII identifier names as follows: Virtuoso supports the above cases which are switchable through the "SQL_UTF8_EXECS" = 1/0 flag in the [Client] section of the Virtuoso INI file. Setting SQL_UTF8_EXECS = 1 enables UTF-8 identifier storage and retrieval, whereas setting SQL_UTF8_EXECS = 0 disables it. The default setting is 0: disabled for backwards compatible option. When an SQL statement comes into the driver(s) it is expanded into unicode (using either the current database character set if it is a narrow string like in SQLExecDirect, or taking it verbatim as in SQLExecDirectW). The unicode string is then encoded into UTF-8 passed to the SQL parser. The SQL parser knows that it will receive UTF-8 so it takes that into account when parsing the national character literals (N'<literal>') and the "normal" literals ('<literal>'). It will however return identifier names in UTF-8, these will then get stored into the DBMS system tables or compared against them depending on the type of statement. http://docs.openlinksw.com/virtuoso/QUALIFIEDNAMES.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Qualified Names 2008-09-09T11:44:52Z Qualified Names http://docs.openlinksw.com/virtuoso/litsbraceescs.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Literals, Brace Escapes 2008-09-09T11:44:52Z Literals, Brace Escapes http://docs.openlinksw.com/virtuoso/CREATETABLE.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE TABLE Statement 2008-09-09T11:44:52Z CREATE TABLE Statement http://docs.openlinksw.com/virtuoso/DROPTABLE.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com DROP TABLE Statement 2008-09-09T11:44:52Z DROP TABLE Statement This statement drops a table. This requires dba privileges or ownership of the table. Any subtables are automatically dropped. Supertables are not affected. http://docs.openlinksw.com/virtuoso/CREATEINDEX.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE INDEX Statement 2008-09-09T11:44:52Z CREATE INDEX Statement This creates an index on a table. Index names must be unique across a qualifier. The ascending / descending column attributes are recognized for compatibility but do not have any effect. The index is defined and populated at the execution of the statement. Pre-existing stored procedures and prepared statements will make use of the new index when appropriate. The UNIQUE attribute enforces uniqueness of the specified columns across the table and subtables where the index is visible. The CLUSTERED attribute is not recommended. It will cause keys to be unprefixed by key id, thus causing the key entries to be intermixed with entries of other CLUSTERED indices with adjacent values of key parts. http://docs.openlinksw.com/virtuoso/DROPINDEX.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com DROP INDEX Statement 2008-09-09T11:44:52Z DROP INDEX Statement This will drop an index, dba privileges or table ownership are required. A table's primary key which has the same name as the table can not be dropped. Optionally, a table name can be given if the index name is not unique. The table name may be qualified. http://docs.openlinksw.com/virtuoso/ALTERTABLE.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com ALTER TABLE Statement 2008-09-09T11:44:52Z ALTER TABLE Statement The ALTER TABLE statement adds or drops columns and renames tables. Adding or dropping a column of a table will create a new version of the table's schema entry. The rows of the altered table will be changed to conform to the new definition when next updated. All newly inserted rows will be in the new row layout. This means that ALTER TABLE itself executes in fixed time without locking the table. The time to update the actual data will be spread over subsequent updates. An added column will have a NULL value on those rows where the new column has not been set. A possible default will only apply to newly inserted rows. http://docs.openlinksw.com/virtuoso/CREATEVIEW.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE VIEW Statement 2008-09-09T11:44:52Z CREATE VIEW Statement http://docs.openlinksw.com/virtuoso/CREATEXMLSCHEMA.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CREATE XML SCHEMA Statement 2008-09-09T11:44:52Z CREATE XML SCHEMA Statement Virtuoso supports registering XML Schemas for use in WITH SCHEMA constraint for column values. The statement contains the whole text of the schema as a string constant, i.e. enclosed in single quotes. This is not the best possible syntax, because single quotes inside the text of schema should be carefully quoted, but this is de-facto standard. If the schema contains number of single quotes (e.g. attributes are in single quotes instead of typically used double quotes), try a system stored procedure DB.DBA.SYS_CREATE_XML_SCHEMA (text_of_schema); that will have the same effect, but is not portable. In principle, you can register any valid XMLSchema, but some features can cause prohibitive loss of performance. It is strongly advised to compose the schema as a "standalone" document that has no references to external DTDs or external generic entities. It is also strongly advised to avoid xs:include and xs:import directives. The only sort of external references that does not affect performance is xs:include or xs:import of a registered "sibling" schema. They say that a schema X is a "sibling" of schema Y if their target namespace URIs have identical protocol names and host names and differs only in local path, and schema X imports Y using relative (not absolute!) URI that contain only relative path, (no protocol and no host). http://docs.openlinksw.com/virtuoso/DROPXMLSCHEMA.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com DROP XML SCHEMA Statement 2008-09-09T11:44:52Z DROP XML SCHEMA Statement This reverts the effect of CREATE XML SCHEMA. The <target URI> should be a string constant that is equal to the value of "targetNamespace" attribute of "xs:schema" element of a previously declared XML schema. The statement signals an error if the XMLSchema to be dropped is used in some WITH SCHEMA constraint. http://docs.openlinksw.com/virtuoso/sequenceobjects.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Sequence Objects 2008-09-09T11:44:52Z Sequence Objects Virtuoso supports sequence objects. These can be used to generate sequential numbers which can be used as unique identifiers. A sequence object is guaranteed never to give the same number twice. Each sequence has a name and a state. The state of a sequence is stored in the database at checkpoint time. Between checkpoints sequence states are logged so that a possible roll forward recovery will not lose information. The SQL functions sequence_next() and sequence_set() are used to access and set the state of sequences. These take the name of the sequence as argument. This is a server/wide unique string. There are no restrictions on the length or character set of the sequence Sequences do not have to be separately created. A sequence object will automatically be generated when first referenced by sequence_next() or sequence_set. http://docs.openlinksw.com/virtuoso/insertSTMT.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com INSERT Statement 2008-09-09T11:44:52Z INSERT Statement New rows (or records) are entered into a database using the INSERT statement. If you have to enter a NULL you can simply use the keyword NULL, as you would a normal value. Since NULL is a special keyword you do not need to enclose it in single quotes. You can specify the columns that you are inserting values into in the insert statement. One should always specify the columns that you are inserting into, in case the order of columns in the database are not as expected, or you are not inserting values into every column. http://docs.openlinksw.com/virtuoso/updatestmt.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com UPDATE Statement 2008-09-09T11:44:52Z UPDATE Statement Existing rows (or records) are changed in the database using the UPDATE statement. NULL values can be utilized using the NULL keyword without any quotes. Since NULL is a special keyword you do not need to enclose it in single quotes, doing so will cause it be read as a string-literal. The update statement is made up by selecting the table to update, the search condition that identifies which rows you want to update, and the column=value of each column you wish to change. http://docs.openlinksw.com/virtuoso/SELECTSTMT.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SELECT Statement 2008-09-09T11:44:52Z SELECT Statement http://docs.openlinksw.com/virtuoso/COMMIT_ROLLBACK.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com COMMIT WORK, ROLLBACK WORK Statement 2008-09-09T11:44:52Z COMMIT WORK, ROLLBACK WORK Statement These statements reset the current transaction. COMMIT WORK leaves all the changes made by the current transaction in effect whereas ROLLBACK work reverses them. In both cases, the transaction will be in a fresh state, having no locks and no changes that could be rolled back. The rollback operation always succeeds, as any change is always reversible until committed. COMMIT WORK may fail if the transaction had been marked to be canceled before the COMMIT WORK operation started. A failed commit has the effect of a rollback but it will signal a SQL STATE descriptive of the error, e.g. 40001 (deadlock). These operations are typically not needed, since the SQLTransact ODBC call and the ODBC autocommit mode are used instead for transaction control. The only use for these statements is within stored procedures, where it may be practical to break a long sequence of operations into several transactions to reduce lock contention. http://docs.openlinksw.com/virtuoso/CHECKPOINT.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com CHECKPOINT, SHUTDOWN Statement 2008-09-09T11:44:52Z CHECKPOINT, SHUTDOWN Statement The checkpoint is a point in the history of a database where all the state is written on disk as a single, consistent image that contains all the state committed so far and no uncommitted state. A transaction log starts after a checkpoint and contains the information to allow the recreation of the effect of transactions committed since the checkpoint. The checkpoint state and the transaction log together allow recovering the database up to the last committed transaction. The CHECKPOINT statement forces a checkpoint to be made. Making the checkpoint allows starting a new transaction log. If no new log name is specified the old log is truncated to length 0 and reused for logging transactions. If the CheckpointAuditTrail option is enabled in virtuoso.ini a new log will be started even if no new log is specified in the checkpoint or shutdown statement. The SHUTDOWN statement performs a CHECKPOINT, and terminates the server upon completion. http://docs.openlinksw.com/virtuoso/spasviewsandtables.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Stored Procedures as Views & Derived Tables 2008-09-09T11:44:52Z Stored Procedures as Views & Derived Tables Virtuoso allows using a stored procedure result set in place of a table. A view may also be defined as a stored procedure. This provides smooth integration to external procedural logic in queries. When a procedure appears as a table, the procedure is called and its result set is inserted into a temporary space. Processing continues from that point on as if the data came from a table. Queries involving procedure views or derived tables are subject to normal join order selection. For this purpose it is possible to associate a cost to a procedure used in a procedure view or derived table. If the option (order) clause is given atthe end of the select, joins are done left to right. If a procedure is in the leftmost position in the from it will be called once for the query, if it is in the second position it will be called once for every row of the leftmost table that passes selection criteria applicable to it and so on. http://docs.openlinksw.com/virtuoso/GRANT.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com GRANT, REVOKE Statement 2008-09-09T11:44:52Z GRANT, REVOKE Statement The GRANT and REVOKE statements are used to define privileges on resources to users and user groups (roles). A resource is a table, view or stored procedure. A grantee can be PUBLIC, meaning any present or future user accounts or a user name. Granting a privilege to a user name means that this user AND any users which have this user as their user group have the privilege. Only a granted privilege can be revoked. The sequence: Is invalid because the privilege being revoked was not granted, instead it was implied by the select on all column to public. To provide further consistent security to remote data, only the DBA group is permitted to use the rexecute(), unless explicitly granted. Caution is required here since any user granted use of rexecute() has full control of the remote data source set-up by the DBA, however limited to the overall abilities of the remote user on the remote data source. Security of UDTs is maintained through normal SQL GRANT and REVOKE statements via a simple extension. You can define the level of access to both native and externally hosted UDTs. Grants for persistent user defined types are persisted into the SYS_GRANTS table. Grants on temporary user defined types are in-memory only and are lost (together with the temporary user defined type definition) when the server is restarted. http://docs.openlinksw.com/virtuoso/SETstmt.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SET Statement 2008-09-09T11:44:52Z SET Statement http://docs.openlinksw.com/virtuoso/besteffortunion.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Best Effort Union 2008-09-09T11:44:52Z Best Effort Union Virtuoso offers a SQL extension for an error tolerant UNION operation. The idea is that when querying multiple remote data sources in a single union construct some of the participating data sources may be allowed to fail while still returning a result for the successfully queried data sources. The construct is introduced by the BEST keyword before UNION or UNION ALL. If a query expression of multiple unions has a single BEST keyword the entire union chain is considered as a best effort union. It is however recommended to have the BEST keyword in FROM of all the UNION keywords. When a run time error occurs during the evaluation of a term in a best effort union the evaluation of the term is interrupted and the union continues with the next term. The partial result set that may have been generated by the failed term is considered when making the result. http://docs.openlinksw.com/virtuoso/aggregates.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Standard and User-Defined Aggregate Functions 2008-09-09T11:44:52Z Standard and User-Defined Aggregate Functions In addition to whole set of standard SQL aggregate functions, Virtuoso provides a method to create application-specific aggregate functions to create complex data structures inside SQL queries. The most evident way to calculate some value that depend on number of rows of a table is to write a stored procedure that opens a cursor, then fetches row after row in a loop and repeatedly modifies some intermediate values ("accumulators") inside the loop. When the fetch operation signals that there are no more data, a final result is calculated from values of "accumulators" E.g. to find an average of all values in a table's column COL, one may open a cursor to fetch values from the COL, then set two "accumulators" TOTAL and CNT to zero, then fetch row after row adding 1 to CNT and adding current value of COL to TOTAL. At the end of loop, an error should be signalled if CNT is zero, otherwise the result is TOTAL divided by CNT. http://docs.openlinksw.com/virtuoso/sqloptimizer.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Virtuoso SQL Optimization 2008-09-09T11:44:52Z Virtuoso SQL Optimization Virtuoso provides a cost based SQL optimizer which performs the following types of query transformation: Virtuoso evaluates various permutations of joined tables against its cost model and determines the best fit, from which it generates a query graph. This query graph can be returned as a result set by the explain() SQL function. The cost model is based on table row counts, defined indices and uniqueness constraints, and column cardinalities, i.e. counts of distinct values in columns. Additionally, histograms can be made for value distribution of individual columns. Virtuoso automatically maintains statistics about tables in the local database. When tables are attached from known types of remote DBMS's, Virtuoso also attempts to retrieve statistics information if available. The sys_stat_analyze or sys_db_stat stored procedures can be used to force an update of statistics, also recompiling all SQL statements or procedures depending on these statistics. Once this is done, this overrides the automatic statistics. The values of automatic statistics can be seen in the SYS_COL_AUTO_STAT table. http://docs.openlinksw.com/virtuoso/sqlinverse.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SQL Inverse Functions 2008-09-09T11:44:52Z SQL Inverse Functions Many virtual database application scenarios require performing various conversions on data in legacy tables. An example of this is currency conversions, conversions between British and metric units, replacing complex composite keys with single numeric row id's and so forth. SQL views are the normal way of implementing such conversions. However, when making queries with selection criteria referencing the results of these conversions we often need to first convert and then test, possibly having to bring data from the source system to the virtual database. Further, we will not be able to use indices that may exist on the legacy system if we first have to convert and only then test the value of a column. Virtuoso introduces an SQL extension for dealing with these issues. Virtuoso allows the definition of two SQL functions that are inverses of each other, for example dollar_to_euro and euro_to_dollar would be examples of inverse functions. http://docs.openlinksw.com/virtuoso/GRAMMAR.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com SQL Grammar 2008-09-09T11:44:52Z SQL Grammar http://docs.openlinksw.com/virtuoso/BITMAPINDICES.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com Bitmap Indices 2008-09-09T11:44:52Z Bitmap Indices A bitmap index is a special type of index that is tailored for being efficient for key columns with relatively few distinct values, i.e. low cardinality key columns. A bitmap index is created with the normal create index statement by putting the bitmap keyword in front of index, as follows: Bitmap indices offer space savings of up to 1000 x in some cases and specially for large tables the savings in I/O can be very significant. A bitmap index can only be used on tables with an integer primary key or in other situations where the last effective key part of the index is an integer. This is understandable since a bitmap index uses a bitmap for representing the values of the last key part, thus having one bitmap for each distinct combination of leading key parts. In the above example, the customer table has an integer c_id column as primary key and a character for the customer's gender and a 2 character field for the state where the customer is located. Thus, to count all the male customers in Massachusetts, one will take the males bitmap and the MA bitmap and perform a bitwise AND of the two. This will have a 1 bit corresponding to the c_id of each male customer in Massachusetts. http://docs.openlinksw.com/virtuoso/urlrewriting.html virtuoso.docs@openlinksw.com virtuoso.docs@openlinksw.com URL rewriting 2008-09-09T11:44:52Z URL rewriting URL rewriting is the act of modifying a source URL prior to the final processing of that URL by a Web Server. The ability to rewrite URLs may be desirable for many reasons that include: