test

Sun StorageTek 5800 System Client API Reference Guide

Chapter 4 Sun StorageTek 5800 System Query Language

This chapter provides information on the 5800 system query language.

Note –

For details of the metadata system and how it is configured, see Chapter 8, “Configuring Metadata and Virtual File System Views” in Sun StorageTek 5800 Storage System Administration Guide.

The following topics are discussed:

Interfaces

The 5800 system Java and C APIs both have a query function that passes a query string to the 5800 system. Queries in the 5800 system are presented to the name-value metadata cache.

Operation

The query format is similar to the where clause of an SQL query. The two main differences are that 5800 system queries do not contain embedded subqueries, and that the only “columns” that are available are the attributes defined in the 5800 system schema.

Many features of the underlying metadata database’s own query language can be used in queries. There is a recommended subset of queries, however, that is most likely to be portable from the 5800 system emulator to a live 5800 system cluster. That subset is described in the sections Supported Expression Types and Queries Not Supported in Version 1.1. These are the query expression types that should work identically on the 5800 system emulator and a live 5800 system cluster.

Supported Data Types

Queries

A query in the 5800 system query language is translated into an equivalent query for the underlying database that implements the query engine. The database used in a live 5800 system is Sun's High Availability Database (HADB). The database used by the 5800 system emulator is ApacheTM Derby. Since the SQL query language used by HADB and Derby differ in substantial ways, a subset of the query language is provided for portability between the cluster and the 5800 system emulator to enable application development in the emulator environment and subsequent deployment of the applications to a live 5800 system.

Translating a Query to the Underlying Database

The following provides a summary of the translation of the 5800 system queries to SQL queries that are presented to the underlying database.

The metadata schema specifies the layout of fields into tables and columns. When the schema is committed, a particular set of actual tables and columns is created in the underlying database that matches the format of the table layout in the schema.

When translating a 5800 system query to SQL, each field name in the query is translated into a reference to the particular column and particular table that represents that field. Typed literal values are translated into a form that the extended metadata cache knows how to deal with. Specifically, most literal values are replaced with an equivalent dynamic parameter. Thus, the list of dynamic parameters that the underlying database uses combines both the dynamic parameters and also many of the literal values from the 5800 system query. Finally, an implicit INNER JOIN is introduced between all the tables containing the translated query fields. Everything else (usually database expression syntax) is left unchanged, allowing almost all the database engine's powerful query syntax to be used with 5800 system queries.

The presence of the INNER JOIN has important consequences when queries are evaluated. An object is only returned by a query when all of the fields referenced by the query itself and all of the fields referenced in the select list of the query all have non-null values. Queries with OR clauses, in particular, can produce non-intuitive results. As an extreme example, consider a query: "fieldA is not null OR fieldB is not null." This query will not select an object unless both fieldA and fieldB are non-null, because of this implicit inner join.

Attribute Format in Queries

Any string in double quotes (for example, "filename") and any dotted string in Java Identifier format (for example, mp3.title) will automatically be treated as an attribute name. The double quotes can optionally be omitted even on a non-dotted name as long as the attribute does not match an SQL reserved word in any of the Sun StorageTek 5800 underlying metadata databases.

Attribute names must appear in the current 5800 system schema to be used in a query. This is because the proper type information about each attribute must be derived to build the query.

SQL Syntax in 5800 System Queries

General Unicode characters outside of the ASCII range in queries are allowed in only two places to the 5800 system. Specifically, both attribute names and literal values may contain general Unicode characters. All text that is not either an attribute name nor a literal value is passed unchanged to the underlying query engine, and must consist of ASCII characters only. An attempt to pass non-ASCII characters in a query will result in an error.

Literals In Queries

This section details the kinds of literals that can occur in 5800 system queries.

Dynamic Parameters

5800 system queries allow dynamic parameters. A dynamic parameter is indicated by the presence of a question mark in the query string (for example, the query name=? AND address=?). The bindParameter call is used in Java to bind typed values for use in place of the question marks.

For the Java API, the syntax is:

     import com.sun.honeycomb.client.PreparedStatement;
     import com.sun.honeycomb.client.QueryResultSet;
     Date date_value= new Date();
     PreparedStatement stmt = new PreparedStatement(
     "system.test.type_date=?");
     stmt.bindParameter(date_value,1);
     QueryResultSet qrs = query(stmt);

For further information, see query (with PreparedStatement), query (with PreparedStatement and selectKeys) and PreparedStatement.

String Literals

String literals are surrounded by single quotes (for example, 'The Lighter Side’). You can embed single quote characters in a query by doubling them (for example, ’Susan’’s House’). Any UTF-8 string can be included in a string literal (except the null character, which is treated as a string terminator by the C API).

Numeric Literals

Only ASCII digits are recognized as numeric literals. For example, 45, -1, 3.14, 5.2E10. Digits from other parts of the Unicode code space will cause a parse error.

Literals for 5800 System Data Types

For each 5800 system data type, there is a syntax to include literals of that type in a query string. The syntax is {type_name ’stringliteral’}. For example, consider the query:

timestamp_field<{timestamp ’2006-10-26T12:00:00Z’}

In particular, this syntax can be used to query for a particular object ID:

system.object_id = {objectid ’0200011e61c159bdfa654e11db8a45cafecafecafe000000000200000000’}

For comparing against binary values, either of the following forms may be used:

binary_field = x’beeffeed’

binary_field = {binary ’beeffeed’}

For more information, see Canonical String Format.

Canonical String Format

Each type in a 5800 system has a canonical representation as a string value. The canonical string representation of each type is shown in Table 4–1.

Table 4–1 Canonical String Representation of Data Types

Data Type  

Canonical String Representation  

STRING

The string itself. 

CHAR

The string itself. 

BINARY

Hexadecimal dump of the value with two hex digits per byte. 

LONG

Result of Long.toString. For example, 88991 or -7975432785.

DOUBLE

Result of Double.toString. For example, 1.45 or NaN or -Infinity or -1.56E200.

DATE

YYYY-mm-dd. For example, 2001-01-01.

TIME

HH:mm:sss. For example, 12:02:01.

TIMESTAMP

YYYY-mm-ddThh:mm:ss.fffZ (time relative to UTC). For example, 1969-12-31T23:59:59.999Z.

OBJECTID

60-digit hexadecimal dump of the objectid.

This canonical string encoding is used in the following places:

The Canonical String Decode Operation

The inverse of the canonical string encoding is used in the following places:

Example 4–1 Virtual View Lookup Operation

If you take a value V and encode it into a string S, and then perform the canonical decode operation on S to get a new value V’. Does V always equal V’? The answer is yes in most cases, but not always.

What is actually guaranteed is the weaker statement that if encode(V) = S and if decode(S)=V’, then encode(V’) is also equal to S.

JDBC and HADB Date and Time Operations

Reserved Words

Some SQL reserved words (such as BETWEEN or LIKE) are allowed in queries and are expected to occur. An SQL reserved word cannot be used as an attribute name unless it is enclosed in double quotes (for example, "FIRST"). Some other SQL reserved words (such as SELECT or CREATE) are forbidden from occurring unquoted in queries. Any query containing these words unquoted will immediately return an error. These forbidden words can be used as attribute names by enclosing them in double quotes.

Supported Expression Types

The following expression types are explicitly supported in this release of the 5800 system:

Examples of Supported Query Expressions

Queries Not Supported in Version 1.1

The following JDBC escapes are not supported:

SQL Words That Are Allowed in Queries

Some SQL reserved words (such as BETWEEN or LIKE) are allowed in queries and are expected to occur. An SQL reserved word cannot be used as an attribute name unless it is enclosed in double quotes (for example, "FIRST").

The following reserved words are allowed:

ABS, ABSOLUTE, AFTER, AND, AS, ASCII, AT, BEFORE, BETWEEN, BINARY, BIT, BIT_LENGTH, BOOLEAN, BOTH, CASE, CAST, CHAR, CHARACTER, CHARACTER_LENGTH, CHAR_LENGTH, COALESCE, COLLATE, COLLATION, CONTAINS,COUNT, CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, DATE, DAY, DEC,DECIMAL, DOUBLE, ELSE, ELSEIF, END, ESCAPE, EXISTS, EXIT, EXPAND,EXTRACT, FALSE, FIRST, FOR, FROM, HOUR, IF, IN, INT, INTEGER, INTERVAL,IS, LCASE, LEADING, LEFT, LIKE, LOWER, MATCH, MAX, MIN, MINUTE, MONTH,NCHAR, NO, NOT, NULL, NUMERIC, OCTET_LENGTH, OF, R, PAD, PI,POSITION, REAL, RIGHT, RTRIM, SECOND, SIZE, SMALLINT, SUBSTRING, THEN,TIME, TIMESTAMP, TIMESTAMPDIFF, TIMESTAMPADD, TIMEZONE_HOUR, TIMEZONE_MINUTE, TO, TRAILING, TRIM,TRUE, UCASE, UNKNOWN, UPPER, VARBINARY, VARCHAR, VARYING, WHEN,WHENEVER, YEAR, ZONE.

Note –

Even if an SQL term is on the list of allowed query terms, it is not guaranteed that the term can actually be used in a working query. The function of this list is to determine words that will not be treated as an identifier unless enclosed in double quotes.

SQL Words That Are Not Allowed in Queries

Some SQL reserved words (such as SELECT or CREATE) are forbidden from occurring unquoted in queries. The 5800 system server will immediately raise an exception when one of the forbidden reserved words is used in a query. These forbidden words can be used as attribute names by enclosing them in double quotes.

The following reserved words are forbidden:

ACTION, ADD, ALL, ALLOCATE, ALTER, ANY, APPLICATION, ARE, AREA, ASC, ASSERTION, ATOMIC, AUTHORIZATION, AVG, BEGIN, BY, CALL, CASCADE, CASCADED, CATALOG, CHECK, CLOSE, COLUMN, COMMIT, COMPRESS, CONNECT, CONNECTION, CONSTRAINT, CONSTRAINTS, CONTINUE, CONVERT, CORRESPONDING, CREATE, CROSS, CURRENT, CURRENT_PATH, CURRENT_SCHEMA, CURRENT_SCHEMAID, CURRENT_USER, CURRENT_USERID, CURSOR, DATA, DEALLOCATE, DECLARE, DEFAULT, DEFERRABLE, DEFERRED, DELETE, DESC, DESCRIBE, DESCRIPTOR, DETERMINISTIC, DIAGNOSTICS, DIRECTORY, DISCONNECT, DISTINCT, DO, DOMAIN, DOUBLEATTRIBUTE, DROP, EACH, EXCEPT, EXCEPTION, EXEC, EXECUTE, EXTERNAL, FETCH, FLOAT, FOREIGN, FOUND, FULL, FUNCTION, GET, GLOBAL, GO, GOTO, GRANT, GROUP, HANDLER, HAVING, IDENTITY, IMMEDIATE, INDEX, INDEXED, INDICATOR, INITIALLY, INNER, INOUT, INPUT, INSENSITIVE, INSERT, INTERSECT, INTO, ISOLATION, JOIN, KEY, LANGUAGE, LAST, LEAVE, LEVEL, LOCAL, LONGATTRIBUTE, LOOP, MODIFIES, MODULE, NAMES, NATIONAL, NATURAL, NEXT, NULLIF, ON, ONLY, OPEN, OPTION, ORDER, OUT, OUTER, OUTPUT, OVERLAPS, OWNER, PARTIAL, PATH, PRECISION, PREPARE, PRESERVE, PRIMARY, PRIOR, PRIVILEGES, PROCEDURE, PUBLIC, READ, READS, REFERENCES, RELATIVE, REPEAT, RESIGNAL, RESTRICT, RETURN, RETURNS, REVOKE, ROLLBACK, ROUTINE, ROW, ROWS, SCHEMA, SCROLL, SECTION, SELECT, SEQ, SEQUENCE, SESSION, SESSION_USER, SESSION_USERID, SET, SIGNAL, SOME, SPACE, SPECIFIC, SQL, SQLCODE, SQLERROR, SQLEXCEPTION, SQLSTATE, SQLWARNING, STATEMENT, STRINGATTRIBUTE, SUM, SYSACC, SYSHGH, SYSLNK, SYSNIX, SYSTBLDEF, SYSTBLDSC, SYSTBT, SYSTBTATT, SYSTBTDEF, SYSUSR, SYSTEM_USER, SYSVIW, SYSVIWCOL, TABLE, TABLETYPE, TEMPORARY, TRANSACTION, TRANSLATE, TRANSLATION, TRIGGER, UNDO, UNION, UNIQUE, UNTIL, UPDATE, USAGE, USER, USING, VALUE, VALUES, VIEW, WHERE, WHILE, WITH, WORK, WRITE, ALLSCHEMAS, ALLTABLES, ALLVIEWS, ALLVIEWTEXTS, ALLCOLUMNS, ALLINDEXES, ALLINDEXCOLS, ALLUSERS, ALLTBTS, TABLEPRIVILEGES, TBTPRIVILEGES, MYSCHEMAS, MYTABLES, MYTBTS, MYVIEWS, SCHEMAVIEWS, DUAL, SCHEMAPRIVILEGES, SCHEMATABLES, STATISTICS, USRTBL, STRINGTABLE, LONGTABLE, DOUBLETABLE.