Chapter 4: VERSANT Query Language

This chapter is a reference to VERSANT Query Language statements and the functions that parse VQL statements, and the data structures that support statement parsing.

For usage notes, please see the chapter "Queries."

Statements

COMMIT

COMMIT

Perform a normal, short transaction commit.

A commit saves your actions to the databases involved and releases short locks. A commit also releases objects from cache memory, erases all savepoints, asserts persistent locks, and starts a new short transaction. A commit makes no changes to transient objects.

Changes made in a short transaction are not visible to other users until you commit them.

See the VERSANT Database Fundamentals Manual for a complete description of a commit.

DELETE

DELETE FROM [ only ] class
[ predicate ]

Delete objects of a class that satisfy a predicate.

Specify the class in the class parameter. To select objects to be deleted, specify a predicate in the predicate parameter; otherwise, all instances of the class will be deleted. To exclude subclasses from evaluation, specify the keyword only. See the "Usage Notes" section for information on how to specify a predicate.

DELETE ( oidval )

Delete the object with the logical object identifier specified in the oidval parameter.

Examples

Delete a specified object:

Delete (9.0.3089)

Delete objects of a class and subclasses using a predicate:

delete from Employee where name like "*Jame*"

Delete objects of a class (only) using a predicate:

delete from only Employee where name like "*Jame*"

INSERT

INSERT INTO class [ attrlist ]
VALUES ( constlist )

In the default database, create a new object of a specified class and set attribute values for the new object.

Elements

class

The name of the class of the new object.

attrlist

An optional list of attributes in the class of the new object.

If attrlist is not specified, the values in the constlist parameter are assumed to be in the same order in which attributes are defined in the class definition.

If attrlist is specified, it should list attributes in the same order as values are supplied in the constlist parameter.

The general syntax of a list of attribute names, each specified as and attr parameter, is:

attr [, attr ...]

See the "Usage Notes" section for information on how to specify an attribute name.

You cannot use the keyword SELFOID or the wildcard character * in an attribute list.

constlist

A list of values for the new object.

The list of values will be applied to the attributes in attrlist in the same order as the attribute names are specified. If attrlist is not specified, values will be applied in the order in which attributes appear in the class definition.

Examples

Insert a new object with values for specified attributes:

insert into Employee (department, name)
values (9.0.3076, "Bill Li")

Insert a new object with values for all attributes:

Insert into Employee
values ("Bill Li", 150000, 9.0.3076)

QUIT

QUIT

Perform a normal application exit.

An exit ends a session if it has not already ended, terminates the application process, and commits the current short transaction.

See the VERSANT Database Fundamentals Manual for a complete description of an application exit.

ROLLBACK

ROLLBACK

Perform a normal, short transaction rollback.

A rollback abandons your actions, releases short locks, and restores databases to conditions at the last commit or checkpoint commit. A rollback also releases objects from cache memory, erases all savepoints, and starts a new short transaction. A rollback makes no changes to transient objects.

See the VERSANT Database Fundamentals Manual for a complete description of a rollback.

SELECT

SELECT  attrlist
   FROM [ only ] class
        [ predicate ]

Find attribute values for objects of a class.

Specify attribute names in attrlist and a class name in class. To select objects whose values are to be returned, specify a predicate in the predicate parameter; otherwise, values for all instances of the class will be returned. To exclude subclasses from evaluation, specify the keyword only.

SELECT  attrlist
  FROM ( oidval ) -> attr
        [ predicate ]

Find attribute values for objects in a vstr.

Specify attribute names in attrlist, the logical object identifier of the object containing the vstr in oidval, and the name of the vstr attribute in attr. To select objects whose values are to be returned, specifiy a predicate in the predicate parameter; otherwise, values for all objects in the vstr will be returned.

SELECT attrlist
FROM ( oidval )

Find attribute values for a single object.

Specify attribute names in attrlist and the logical object identifier of the object in oidval.

Elements

Following is an explanation of the elements of the various forms of the SELECT statement.

attrlist

A comma delimited list of attribute names or a wildcard character.

The general syntax is:

attr [, attr.. ] [ SELFOID ] | *

To return values for all visible attributes of the class and its subclasses, use the wildcard character *.

If you list individual attribute names, you can also use the keyword SELFOID to get the logical object identifier for the returned object. You will not receive the logical object identifier if you use the wildcard character.

See the "Usage Notes" section for information on how to specify an attribute name.

class

The name of the class over which the query operates.

only

By default, the query will also evaluate and return instances of subclasses. To exclude subclasses, prefix the class name with the keyword only.

oidval

The logical object identifier or "loid" of the instance object over which the query operates.

predicate

The query predicate.

If you do not specify a predicate in the forms of SELECT that take an optional predicate, then all instances of the class or vstr are returned.

See the "Usage Notes" section for information on how to specify a predicate.

Examples

Select attribute from class and subclasses

Select value of name from all instances of Person and its subclasses:

select name from Person

Select attribute from class but not subclasses

Select value of name from all instances of Person:

select name from only Person

Select loid from class and subclasses

Select value of logical object identifier from all instances of Employee and its subclasses:

select selfoid from Employee

Select with predicate

Select values of all visible attributes from the instances of Employee and its subclasses that satisfy a predicate:

select * from Employee where name like "*Jame*"

Select value of name using a full attribute name in the predicate:

select * from Employee
where Person::name like "*James*"

Select with multiple predicates

Select value of name from the instances of Employee and its subclasses that satisfy multiple predicates:

select name from Employee
where salary > 45000.7 and name like "*Jame*"

Select with a predicate that tests for a null link

Select name from Employee and subclasses where the department link is not of type Department (meaning that the link is null):

select name from Employee
where department not_isa Department

Select with substitution parameters

Select name from the instances of Employee and its subclasses that satisfy multiple predicates whose parameters $1 and $3 are substituted at runtime:

select name from Employee
where salary > $3 and name like $1

Select from a single object

Select all values from the object with the specified logical object identifier:

select * from (9.0.3076)

Select from a class using a path expression

Select all values from Employee and subclasses whose department attribute contains a link to a Department object with a name attribute that matches a predicate:

select * from Employee
where department -> name = "RD"

Select from a vstr using a path expression

Select name from objects in a vstr that satisfy a predicate. The vstr that will be searched is the employees attribute of the Department object whose loid is 9.0.3076.

select name from (9.0.3076) -> employees
where salary > 30000.0

UPDATE

UPDATE [ only ] class
SET updatelist
[ predicate ]

Modify attributes of objects of a class.

Specify update expressions in updatelist and a class name in class. To select objects to be updated, specify a predicate in the predicate parameter; otherwise, values for all instance of the class will be changed. To exclude subclasses from updating, specify the keyword only.

UPDATE ( oidval )
SET updatelist

Modify attributes of a specified object.

Specify the logical object identifier of the object to be updated in oidval and update expressions in updatelist.

Elements

Following is an explanation of the elements of the various forms of the UPDATE statement.

class

The name of the class containing objects to be updated.

only

By default, instances of both the specified class and its subclasses will be evaluated and updated. To exclude evaluation and updating of instances of subclasses, prefix the class name with the keyword only.

updatelist

A comma delimited list of individual update expressions.

The general syntax is:

update_expr [, update_expr ...]

predicate

The predicate that selects instances to be updated.

See the "Usage Notes" section for information on how to specify a predicate.

oidval

The logical object identifier or "loid" of the instance object over which the update operates.

Update expressions

The updatelist parameter consists of a list of update expressions. An update expression can modify object attributes.

Set value syntax

To set an attribute value, use the following syntax for update_expr:

attr = const

Add elements

To add elements to a multi-value attribute (such as a vstr or link vstr):

attr += const

In an update expression, specify an attribute name in the attr parameter. See the "Usage Notes" section for information on how to specify an attribute name.

In an update expression, specify a modified or new value in the const parameter. A const can be one of the following literal values:

float

A number of type float.

int
A number of type int.

string
A string (use backquotes if special characters).

oidval

An object loid expressed with syntax nn.nn.nn.

constaggr

A list of constant values with comma delimiters and enclosed with curly braces. For example:

{1.3, -3.05, 4.3}

You cannot specify null in a const or constaggr parameter.

Examples

Update attribute in specified object:

update (9.0.3089)
set employees += 9.0.3079,
name = "Marketing"

Update attribute in class and subclasses using predicate:

update Employee
set salary = 5.765e3
where name = "James"

Update attribute in class but not subclasses using predicate:

update only Employee
set salary = 5765.7
where name = "James"

Add the object with the loid 9.9.3079 to the vstr attribute employees in all instances of Department:

update Department
set employees += 9.0.3079

Add two objects to a vstr attribute in all instances of a class:

update Department
set employees += {9.0.3079, 9.0.3077}

Add the object with the loid 1.0.3445 to the vstr attribute employees in the instances of Department whose name attribute is "RD":

update    Department
   set    employees += 1.0.3445
   where  name = "RD"

Add two objects to the vstr attribute employees in the instances of Department whose name attribute is "RD":

update    Department
   set    employees += { 1.0.3445, 1.0.3446 }
   where  name = "RD"

Parsing Functions

The following C/VERSANT functions parse VQL statements.

o_freequery()

void o_freequery( o_parseresult* parseresult );

Deallocate memory allocated in o_parsequery() to hold a parse result.

See the chapter "VERSANT Query Language" in the Database Fundamentals Manual for usage notes.

This function does not release the memory of the o_parseresult struct itself.

If the parsing of a query result succeeds, o_parsequery() returns O_OK and places the parsed result in the output parameter of type o_parseresult. Since o_parsequery() allocates memory from the object cache to hold the parse results, you must call o_freequery() to release the memory when the query result is no longer needed.

If the parsing of a query result fails, o_parsequery() returns an error number of type o_errno and places the parse error message and the offset of the token (where the error occurs) in the prs_err field of the o_parseresult structure. Since no memory is allocated in the case of a failure, in this case you do not need to call o_freequery().

o_parsequery()

o_err o_parsequery(

char*           querystring,
o_parseresult*  parseresult,
   o_dbname        dbname );

Parse a VQL statement string, place the results in an o_parseresult structure, and return O_OK if successful.

Following are the elements of o_parsequery().

querystring

The input VQL string to be parsed.

parseresult

The output parse results.

See the "Data Types" chapter for information about the o_parseresult data type.

dbname

The name of the database on which the VQL operation is to be performed.

If the query is parsed successfully, o_parsequery() returns O_OK and places the parsed result in the parseresult output paramter.

If the parsing of any statement in the querystring parameter fails, o_parsequery() returns an o_errno error number, and places the parser error message together with token offset (where the error occured) in the parseresult parameter. In this case, no parse result of any statement is presented in the parseresult output parameter, except for the error information.

The input statement can contain one or many VQL statements. After invoking this method, you can iterate through the parse result and use standard C/VERSANT functions to execute each VQL statement found in the input statement.

Usage

• A parse result cannot be used across a session boundary.

• You must allocate memory for the output parseresult parameter before invoking this method.

Afterwards, you must deallocate memory used by the parse result with o_freequery().

• The o_parsequery() function is thread-safe.

A process global mutex is used to protect the parser internal data. The performance implication is that the execution of o_parsequery() is serialized for threads within a process, which means at any given point of time, only one thread within a process can proceed with its o_parsequery() execution. If there is any other thread of the same process invoking o_parsequery() at the same time, this thread will wait until the ongoing execution of o_parsequery() from the other thread completes.

Error messages

The error messages may be returned by o_parsequery():

OM_PSR_ATTR_NOT_FOUND

An given attribute is not found.

OM_PSR_ATTR_NOT_FOUND_IN_DOMAIN

An attribute is not in a given type.

OM_PSR_ATTRCLASS_NOT_FOUND

Type for a given attribute is not found.

OM_PSR_ATTRS_OUTBOUND

Number of attributes in SELECT, UPDATE, INSERT list goes beyond the limit.

OM_PSR_BCD_NOT_SUPPORT

BCD type input value is not supported yet.

OM_PSR_CLASS_NOT_FOUND

A given class is not found.

OM_PSR_DOMAIN_NOT_FOUND

A given type is not found.

OM_PSR_FIND_ATTR_FAIL

Failed to find all attribute objects for a given class.

OM_PSR_MIXED_TYPE

Mixed data types are used in a set of constants.

OM_PSR_NO_VALUE_INSERT

No value to insert for a given attribute.

OM_PSR_NOMEM

Parser unable to allocate memory.

OM_PSR_NOT_AGG_OF_CHAR

Collection of char is not yet supported.

OM_PSR_NOT_AGG_TO_SCALAR

A single value attribute is not allowed to be assigned with multi-values data.

OM_PSR_NULL_RESULT

Null parseresult pointer is passed in.

OM_PSR_NULLQUERY

Null query statement.

OM_PSR_OBJCLASS_NOT_FOUND

Class object for a given object is not found.

OM_PSR_PARAMETER_TWICE

The same parameter index can not be used twice in the query.

OM_PSR_PATHATTRS_OUTBOUND

Number of attributes in path expression goes beyond the limit.

OM_PSR_SET_PREDICATE_NOT_SUPPORTED

Multi-value constant in predicate is not supported in this release.

OM_PSR_SYNTAX_ERROR

Syntax error on a given token offset.

OM_PSR_TYPE_MISMATCH

Type mismatch on a given attribute.

OM_PSR_TYPE_OVERFLOW

Constant value overflows or underflows a given type.

OM_PSR_UNSUPPORTED_DBTYPE

Encountered VERSANT type that is not yet supported.

The o_parsequery() function may also return other VERSANT errors, which are documented in the VERSANT Database Administration Manual.

Data Types

o_cmdtype

typedef enum o_cmdtype {

O_QRY_SELECT,
O_QRY_SELOBJ,
O_QRY_INSERT,
O_QRY_DELETE,
O_QRY_DELOBJ,
O_QRY_UPDATE,
O_QRY_UPDOBJ,
O_QRY_ROLLBACK,
O_QRY_COMMIT,
O_QRY_QUIT,
O_QRY_EMPTY

} o_cmdtype;

The statement type as returned to a parse block.

See o_parseblock for further information.

o_param

typedef struct o_param {

o_4b prm_index;
o_predterm* prm_predterm;

} o_param;

Structure for parameter substitutes.

Elements are:

prm_index

The parameter index given in the query string.

prm_predterm

A pointer to the o_predterm predicate where the substitution occurs.

If there are any parameters in the predicates of a query, parsing the query with o_parsequery() fills up an o_param struct for each parameter, with the pointer in o_param pointing to the o_predterm where the parameter substitution should be applied at execution time.

Each parameter of type o_param is inserted into a Vstr of o_param parameters based on the value of the parameter index. The final Vstr of parameters pointed to by the prb_paramvstr in the parse block is sorted based on the parameter index value in o_param.

Parameter indexes need not be in a consecutive value range. For example, suppose that there are only two parameters, $100 and $3, in the query. In the result Vstr of parmeters, $3 comes first and $100 sits in the second slot of the Vstr.

Suppose that you have the following query:

SELECT name
FROM Employee
WHERE salary > $4 or salary < $2 ;

In the above case, there will be two entries in prb_paramvstr field of the parse block that correspond to the two parameters that are to be filled. Within the o_param structure, there is a pointer prm_predterm to the o_predterm where the field key is null, which is where the parameter should be substituted. The index value of the parameter is also placed in the structure.

o_parserr

typedef struct o_parserr {

char prer_errmsg [ PSR_MAXP_ERRMSG ];
int prer_tokenpos;

} o_parserr;

Parser error information.

Elements are:

prer_errmsg

Parser error message.

The maximum length of the error message, PSR_MAXP_ERRMSG, is 256 bytes.

prer_tokenpos

The offset to the token that caused the error.

o_parseblock

typedef struct o_parseblock {

o_predblock*  prb_predicate;
o_clsname     prb_classname;
o_cmdtype     prb_command;
o_vstr        prb_prjvstr;
o_object      prb_vstrobj;
o_attrname    prb_vstrattr;
o_bool        prb_options;
o_vstr*       prb_paramvstr;

} o_parseblock;

The parse block for a VQL statement, which hold the parsed results for a VQL statement of a query string.

Elements are:

prb_predicate

Query predicate.

prb_classname

Name of class over which query operates.

prb_command

The type of VQL statement performed.

prb_prjvstr

A vstr of pointers to structs of type o_projection.

prb_vstrobj

Vstr to be used for select with vstr.

If the prb_command parameter is O_QRY_SELOBJ, O_QRY_UPDOBJ, or O_QRY_DELOBJ, then the SELECT, UPDATE, or DELETE statement specified a loid in the FROM clause. In this case, the prb_vstrobj field will hold the loid of the input value oidval.

prb_vstrattr

Attribute name for select with vstr attribute.

prb_options

Options for path query performed with o_pathselect().

prb_paramvstr

A pointer to a vstr of containg parameter substitutes of type o_param.

Command type

The prb_command parameter will contain the type of statement performed as a value of type o_cmdtype. Possible values are:

O_QRY_SELECT

A SELECT statement over a class or a vstr of objects contained in an attribute.

O_QRY_SELOBJ

A SELECT statement specifying a loid in the FROM clause:

SELECT attrlist
FROM ( oidval );

In this case, the prb_vstrobj field will hold the loid of the input value oidval.

O_QRY_INSERT

An INSERT statement.

O_QRY_DELETE

A DELETE statement.

O_QRY_DELOBJ

A DELETE over an object statement.

O_QRY_UPDATE

An UPDATE statement.

O_QRY_UPDOBJ

An UPDATE over an object statement.

O_QRY_ROLLBACK

A ROLLBACK statement.

O_QRY_COMMIT

A COMMIT statement.

O_QRY_QUIT

An application exit statement.

If a SELECT, UPDATE or DELETE statement has occurred, you can pass the following five fields into the o_pathselect() function to execute the query:

prb_predicate
prb_classname
prb_vstrobj
prb_vstrattr
prb_options

If a SELOBJ, UPDOBJ, or DELOBJ statement has occurred, the field prb_vstrobj holds the object value for the input loid.

If a SELECT, UPDATE or INSERT statement has occurred, the field prb_prjvstr contains a vstr of pointers to structs of type o_projection which describe which attributes to operate on and what the corresponding operand values are.

If there are parameter substitution values, the field prb_paramvstr contains a vstr of pointers to parameter values of type o_param.

o_parseresult

typedef struct o_parseresult {

o_dbname   prs_dbname;
o_vstr     prs_pblkvstr;
o_parserr  prs_err;
o_psrmem   prs_memused;

} o_parseresult;

Structure to hold the result of parsing a VQL statement.

Elements are:

prs_dbname

Database name.

prs_pblkvstr

A vstr of pointers to o_parseblock structs.

Each o_parseblock holds the parsed result of a statement, if the parsing of all of the statements succeeded.

prs_err

Parsing error information.

prs_memused

Handles of memories that are allocated.

o_projection

typedef struct o_projection {

o_attrname  prj_attrname;
o_setcmd    prj_setcmd;
o_bufdesc   prj_buf;

} o_projection;

Function parameters whose elements depend on the type of statement parsed.

A parse block will contain a prb_prjvstr parameter, which is a vstr of pointers to structs of type o_projection.

Elements are:

prj_attrname

Attribute name.

prj_setcmd

Type of operation.

prj_buf

Values to be set or inserted.

How the o_projection struct is filled depends on the value of the prb_command parameter of the returned parse block. The prb_command parameter is of type o_cmdtype.

Following are possible values of the prb_command parameter and the resulting values that will be placed in the o_projection struct.

O_QRY_SELECT

If the prb_command parameter contains O_QRY_SELECT, only the prj_attrname field of the o_projection struct is filled. The remaining two field in the structure are meaningless and are zeroed out.

O_QRY_INSERT

If the prb_command parameter contains O_QRY_INSERT, the prj_attrname and prj_buf fields are filled. The prj_setcmd field is meaningless.

O_QRY_UPDATE, O_QRY_UPDOBJ

If the prb_command parameter contains O_QRY_UPDATE, the prj_attrname, prj_setcmd, and prj_buf fields are filled. The prj_setcmd indicates what kind of SET operation is to be applied.

o_setcmd

typedef enum o_setcmd {

VQL_ASSIGN,
VQL_APPEND

} o_setcmd;

If the query is an UPDATE statement, the parameter prj_setcmd is of type o_setcmd and indicates type of SET operation to perform on the attribute.

VQL_ASSIGN

Assign new value(s) to a single-value or vstr attribute.

If the attribute is a single value attribute, prj_setcmd parameter is always VQL_ASSIGN.

VQL_APPEND

Add new values to a vstr attribute.

o_psrmem

typedef struct o_psrmem {

o_vstr prm_memp;
o_vstr prm_vstrp;

} o_psrmem;

Memory that are allocated to hold the parse result:

Elements are:

prm_memp

A vstr of memory pointers.

prm_vstrp

A vstr of vstr pointers.

The o_psrmem struct is an internal structure used only by the o_parsequery() and o_freequery() functions.

This online documentation is confidential and proprietary to Versant Corporation and is licensed to you, or to your organization, pursuant to the terms of an agreement between you and Versant that restricts the use of this documentation. Please refer to the agreement for more information or call Versant at 510-789-1500 with any questions.