FastObjects OQL Reference

Transcription

1

2 FastObjects Release 12.0 Copyright Versant Software LLC and Copyright Actian Corporation. All rights reserved. The software described in this document is subject to change without notice. This document does not represent a commitment on the part of Versant or Actian. The software is furnished under a license agreement or nondisclosure agreement and may be used or copied only in accordance with the terms of the agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or for any purpose without the express written permission of Actian. Versant, Versant Object Database and FastObjects are either registered trademarks or trademarks of Versant Software LLC in the United States and/or other countries. Java and all Java-based marks are trademarks or registered trademarks of Oracle Corporation in the United States and other countries. Eclipse and Built on Eclipse are trademarks of Eclipse Foundation, Inc. Microsoft, Windows, Visual C#, Visual Basic, Visual J#, and ActiveX are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. All other products are a registered trademark or trademark of their respective company in the United States and/or other countries V9-6

3 Table of Contents Contact Information for Actian... vii 1. Overview About this Guide Prerequisite Knowledge Using FastObjects With Third-party Indexing OQL The Object Query Language The SELECT Statement Path Expressions Extents Result Sets SELECT Statement Syntax Summary The FROM Clause The WHERE Clause Wildcards Boolean Operators AND, OR, and NOT Standard Comparison Operators Special Comparison Qualifiers Comparing null Object References The IN extent Clause The ORDER BY Clause The COUNT Statement Using the COUNT Statement Within a WHERE Clause The EXISTS and EXISTS IN Statements Using the EXISTS Statement within a WHERE Clause The FOR ALL Statement The DEFINE Statement The ELEMENT Statement Querying on Object Identity The Object Identifier OID The OID in an OQL Query Additional Notes Casting The DISTINCT Keyword FastObjects OQL Warning and Error Codes Warning Codes Error Codes BNC Syntax Diagrams OQL General Syntax OQL COUNT Statement Syntax iii

4 OQL EXISTS, EXISTS IN Statement Syntax OQL FOR ALL Statement Syntax OQL DEFINE Statement Syntax OQL ELEMENT Statement Syntax OQL COUNT Statement in WHERE Clause Index iv

5 List of Tables 2.1. Standard OQL Comparison Operators Components of the Object ID FastObjects OQL Warning Codes FastObjects OQL Error Codes v

6 vi

7 Contact Information for Actian You can obtain the latest information about Actian products by contacting either of our main office locations, visiting our web sites, or sending us an . Actian Office Locations Actian Corporation is headquartered in Redwood City, California. Versant GmbH is responsible for European operations and has headquarters in Hamburg, Germany. Actian Corporate Headquarters 500 Arguello Street, Suite 200 Redwood City, CA USA [TEL] [FAX] Versant GmbH Halenreie 42 D Hamburg Germany +49 (0) [TEL] +49 (0) [FAX] Actian Web Site For the latest corporate and product news, visit the Actian web site at Actian Versant Products For inquiries about Versant products and services, contact: info@versant.com For help in using Versant products, contact Technical Support at: versant_support@actian.com The Actian Customer Portal provides all the essential information and valuable resources needed by developers using Versant Object Database or Versant FastObjects. Visit the Actian Customer Portal at support.actian.com vii

8 Please send feedback regarding this guide to: viii

9 Chapter 1. Overview This chapter describes the purpose and organization of this guide, and defines what prerequisite knowledge you need in order to use this book About this Guide This document describes the Object Query Language (OQL) syntax as implemented by FastObjects for its various SDKs. The OQL is defined by the Object Database Management Group (ODMG). The FastObjects implementation is a nearly complete reflection of the ODMG standard Prerequisite Knowledge This guide assumes that you are familiar with object-oriented concepts and programming Using FastObjects With Third-party Indexing Some applications may need an indexing scheme, such as full-text, that goes beyond what you can accomplish with the standard FastObjects API. For these situations, FastObjects provides a Service Provider Interface (SPI) for integrating third-party indexing engines with FastObjects databases and your object applications. Using the FastObjects integration, your third-party index may even be used in OQL queries. For information about how you can use third-party indexing engines, please contact FastObjects. Contact information can be found at the front of this guide. 1

10 2

11 Chapter 2. OQL The Object Query Language The ODMG Object Query Language (OQL) is a standard query language for object database management systems. It is a declarative query language based on the syntax of Structured Query Language (SQL), the query language used with relational databases. The basic querying construct is the same as that used in SQL, that is, a SELECT...FROM...WHERE statement. OQL was designed to be object-oriented. Queries are specified using objects and their attributes (data-members). Queries return sets of objects. The complex relationships in an object database can be easily navigated using the same class-member paradigm used by object-oriented programming languages. This can often lead to increased performance over SQL, where resource-consuming join processes are necessary to capture relationships. OQL may be used as an embedded language or as a standalone query language. FastObjects supports both. As an embedded language, OQL queries can be used directly in your application programs. Programs can embed OQL queries, and receive results in the native data types of the programming language being used. OQL statements are simply text strings meaning that you use the standard string representation for your programming language to express the query. As an example of standalone use, you can execute OQL queries directly using the FastObjects Developer's Workbench. The following sections discuss the OQL language. For detailed information about performing queries within FastObjects, refer to Programmer's Guide and API Reference included with your FastObjects installation. The ODMG OQL Standard You may also want to read the standard definition of the Object Query Language, published by the Object Data Management Group. Visit the ODMG web-site at for more information The SELECT Statement As in SQL, the OQL SELECT statement is the basic construct for querying databases. However, while SQL works with tables, rows, and columns, OQL works with extents, objects, and members. A SELECT statement is a query expression that accepts one or more extents (and sometimes sets) as input in the FROM clause, producing a new result-set as output. The WHERE clause allows you to specify which objects are selected from the extent. If the WHERE clause is omitted, no filtering is performed. The ORDER BY clause will sort the result-set in the specified sequence. 3

12 The SELECT Statement Procedure 2.1. SELECT Statement The Basic Components 1. SELECT [DISTINCT] Select objects to be placed in the result-set by specifying class or class-member names. If the key word DISTINCT is provided duplicates are removed. 2. FROM Specify where to search, i.e., the extents or sets to select from. 3. WHERE Specify the filtering conditions as comparisons on member values (optional). 4. ORDER BY Specify the sorting sequence of result-set based on the values of data-members (optional). All SELECT statements must include a FROM clause. The WHERE and ORDER BY clauses are optional. Additional clauses and OQL constructs such as COUNT and EXISTS are also supported. These components of the SELECT statement are described in detail in the following sections. Also presented are example query statements describing the specific OQL syntax. You can run these example OQL queries using a sample database and the Developer's Workbench Path Expressions Path expressions allow you to traverse relationship paths that exist among objects. Either the reference (.) or pointer (->) notation is allowed and can be used interchangeably. OQL makes no distinction between pointers, embedded objects, or other references. You can specify all containment and relationship references using either symbol. The following is a partial listing of an example Supplier class that contains a data-member named company of type Company. The Company class contains a string data-member called name. class Supplier { //... Company company; //... 4

13 The SELECT Statement }; class Company { //... string name; //... }; A path expression is used to gain access to the name member of class Company. SELECT supplier FROM SupplierExtent AS supplier WHERE supplier.company.name= "World Wide Widgets" Please note the following two restrictions when using path expressions Access modifiers for class members in a path expression are ignored. However, you can access private, protected, namespace-visible and public members. Path expressions may conflict with fully-qualified class names, which use the dot symbol as a namespace delimiter. To avoid confusion, it is especially important to define an alias in the [Persistent] attribute and to use the alias in the extent. Dots that are used in fully qualified class names within a path expression must be escaped. For example, "SELECT supplier FROM BusinessObjects\.SupplierExtent... " Extents An extent contains all objects in a database that belong to a specific persistence capable class. OQL queries operate on extents, whereas SQL queries use tables. When formulating a query, use the name of the class plus the word Extent to specify the extent name. If, for example, you have a class named Product, the extent for the class would be called ProductExtent. The following is an example of querying a class named Product. Note that the AS statement defines the set variable, which is an alias for the extent. SELECT * FROM ProductExtent AS product 5

14 The SELECT Statement The statement above returns all Product objects. The Set-Variable When you use an extent in a SELECT statement, an explicit extent variable, the set-variable, is associated with the extent. This variable acts as a surrogate name for every element of the extent set, allowing you to specify class members in the WHERE clause and result-set specification of a query. In the following statement, the objects of the extent are associated with the set-variable product. By using the variable product, you can select objects based on the value of a data-member of the class in your query. SELECT * FROM ProductExtent AS product WHERE product.title_ = "Meteora" This example selects the object (product) from the ProductExtent whose title is Meteora. You can also specify the extent variable in the result-set description (refer to Section 2.1.3, Result Sets pg. 7). SELECT product FROM ProductExtent AS product WHERE product.title_ = "Meteora" This example produces the same result as the previous example. Extent Aliases An alias name can be defined for an extent or other collection. Temporary aliases are defined directly in OQL using the DEFINE EXTENT statement. In the following example, an extent alias named Products is defined for the class Product. DEFINE EXTENT Products FOR Product; This example defines an alias for the ProductExtent. 6

15 The SELECT Statement The alias, Products, can then be used in subsequent OQL statements, instead of the default ProductExtent. The following statement selects all Product objects. DEFINE EXTENT Products FOR Product; SELECT * FROM Products The DEFINE EXTENT statement is optional. It is most useful for creating temporary shorthand aliases for extents Result Sets A query returns a set of objects known as the result-set. The elements of a result-set are specified in the main clause of the SELECT statement (immediately following the SELECT keyword). The result-set elements are either the same type as the set-variable defined in the FROM clause or that of a data-member determined by a path-expression rooted to the set-variable (refer to Section 2.2, The FROM Clause pg. 12). FastObjects supports two methods for specifying selection members: All members of the queried set or extent (* option, or set-variable ). A specific member of the queried set or extent ( set-variable.member or path-expression). In the first method, the result-set variable is the same as the set-variable specified in the FROM statement. This means that the type of the objects that are being queried is the same object type that you want to see in the result-set. In the second method, the result-set element type is that of the data-member on the right-hand side of the path-expression. Compare the following examples: Example 1: SELECT * The type of the result-set elements is the same as the type of the set-variable. The set-variable is defined in the FROM clause. FROM ProductExtent AS product 7

16 The SELECT Statement The set-variable ( product) is of type Product. Example 2: SELECT product Here, again, the set-variable is used as the type of the result-set elements. FROM product IN ProductExtent The result-set is of type Product Example 3: SELECT product.name The type of the result-set elements is the same as the type of the name data-member. (Again, the set-variable is defined in the FROM clause.) FROM ProductExtent AS product The set-variable type is Product and the class must define a data-member named name (which is a string in the example database). These forms are explained in detail later. (Also, refer to Section 2.1.2, Extents pg. 5 and Section 2.2, The FROM Clause pg. 12.) Selecting All Members The (*) option of the SELECT statement selects all members of a class. SELECT * FROM ProductExtent By stating (*), every member of the queried set is selected and returned in the result-set. Similarly, you may specify the extent or set variable instead of the (*) option. SELECT product FROM ProductExtent AS product 8

17 The SELECT Statement The use of an extent-variable, in this case product, also selects all members for the result-set. Selecting All Instances of a Member of an Extent By using a path expression, you can direct the result-set to be a set of members of a set-variable. The following query returns a set of string objects (the names of all products in the database). SELECT product.name FROM ProductExtent AS product The result-set is a FastObjects.IQueryResult instance that contains string elements. What this means in practice is that your query need not return a result-set of persistent objects. For example, if the member is of type float the result-set will be a set of float values. The following query returns a result-set of float values containing all Product.unitPrice values in the database. SELECT product.unitprice FROM ProductExtent AS product. This query returns a FastObjects.IQueryResult instance that contains float values representing the unitprice values for all products in the database. In the preceding examples, you could specify a data-member of the set-variable (e.g., product.unitprice) in order to select the members into the result-set. However, selecting a list of members (i.e., multiple members) is currently not supported. The following query is not allowed and would result in the error type error: not yet implemented: comma separated projections not supported yet. SELECT product.name, product.unitprice FROM ProductExtent AS product Again, this query will result in an error. 9

18 The SELECT Statement Selecting A Single Embedded Set Member Collections are stored embedded in another object as a member. To select an embedded collection, simply specify the collection member name in the result-set. The following is a partial listing of the Order class, which contains an ArrayList of OrderDetail objects. class Order { //... [ItemType(typeof(OrderDetail))] private ArrayList details; //... }; The ArrayList of order details can be selected by specifying it in the result list. SELECT Order.details FROM OrderExtent as order WHERE order.orderno_ = 17 This query finds the set of order details for the order with order no. 17. Filtering The WHERE Clause Most examples in this section selected all elements of the extent and placed them in the result-set. The actual number of objects that are selected and placed into the result-set is also dependent on the WHERE clause. If the WHERE clause is omitted, every object in the extent is selected. By providing query criteria in the WHERE clause, you can select only specific objects whose attribute values meet the specified criteria.... WHERE product.name = "Programming Windows"... The WHERE clause is described in Section 2.3, The WHERE Clause pg

19 The SELECT Statement Additional Notes Regarding Result Sets The result does not necessarily contain accessible or even valid object references. The query optimizer makes every attempt to choose the best possible query execution plan. Depending on the actual choices made by the optimizer, an object in the result-set may or may not be accessible due to locking, user authorization, etc. It is also possible that a reference to an already deleted object may be returned depending on whether the query made its choices based on objects in local memory SELECT Statement Syntax Summary Following is a syntax summary for the SELECT statement. The syntax described is a subset of the ODMG specification and represents the FastObjects OQL implementation. In this and following syntax declarations, OQL keywords and commands are displayed as COMMAND, parameters are displayed as parameter, optional elements are displayed as optional-element, and literal values are displayed as literal. Where one of a collection of values may be used, the collection is enclosed in braces ({}) with the values separated by or-bars ( ). Only one of the values is to be used in the expression. SELECT result-set FROM set-definition, set-definition WHERE expression ORDER BY member-list The following are syntax summaries for the various parameters describing the statement clauses. result-set: { * set-variable path-expression } (refer to Section 2.1.3, Result Sets pg. 7) set-definition: { set AS set-variable set-variable IN set } set: { extent embedded-set result-set-id } expression: compare-predicate { AND OR } compare-predicate compare-predicate: path-expression comparison-operator { literal COUNT-statement operator number EXISTS-statement = { true false } } path-expression: set-variable dot additional indirections member-name (refer to Section 2.1.1, Path Expressions pg. 4) dot: {. -> } literal: literal FastObjects basetype (string, int, etc.) 11

20 The FROM Clause comparison-operator: { = ==!= <> > < >= <= } LIKE NOT LIKE (and additional FastObjects-supplied operator qualifiers Section 2.3.4, Special Comparison Qualifiers pg. 16) member-list: path-expression { ASC DESC }, path expression { ASC DESC } COUNT-statement : (refer to Section 2.5, The COUNT Statement pg. 20) EXISTS-statement: (refer to Section 2.6, The EXISTS and EXISTS IN Statements pg. 23) 2.2. The FROM Clause Use the FROM clause to select the sets that are to be queried. The sets listed in the FROM clause can be an extent, an embedded-set, or a result-set from another query. The FROM clause is a required part of the SELECT statement; at least one set must be listed. Extents can be of any type, including base type collections, which can then be used for polymorphic access in the result-set. An extent always has a set-variable associated with it. OQL allows two methods of associating a set-variable to an extent. FROM with IN... FROM product IN ProductExtent FROM with AS... FROM ProductExtent AS product In the first form, the IN keyword is mandatory. However, the AS keyword in the second form is not mandatory. In both forms, the variable product represents an object of the set and is used in the other clauses of the SELECT statement. Only one extent is allowed in a FROM clause, because only one extent variable can be specified in the result-set immediately following the SELECT statement. The result-set of another query may be used in the FROM clause. The result-set must first be defined using the DEFINE statement (refer to Section 2.8, The DEFINE Statement pg. 25). 12

21 The FROM Clause Selecting From Embedded Set Members The FROM clause is also used to associate a variable with an embedded set member of a class. The variable can then be used in the selection criteria of the WHERE clause. The following is a partial listing of the Order class, which contains an ArrayList of OrderDetail objects. C# class Order { //... [ItemType( typeof( OrderDetail ) )] private ArrayList details; //... }; First, a variable is associated with the collection in the FROM clause. This variable can then be used in the WHERE clause of the statement to specify a search criterion based on the name of the manager. Here is an example. SELECT order FROM OrderExtent AS order, order.details_ AS detail WHERE detail.product.name_ = "Programming Windows" This query finds all orders that contain the product Programming Windows by searching the OrderDetail collections of each Order object. You can also specify a member of an embedded collection directly, without defining a variable. SELECT order FROM OrderExtent AS order WHERE order.details_.product.name_ = "Programming Windows" These two queries are equivalent. 13

22 The WHERE Clause 2.3. The WHERE Clause Use the WHERE clause to specify the search conditions (shown in the preceding example as the compare-predicate of a query). The search conditions consist of SQL-like comparison strings, comparing class member values and literal constants. The literal constants may be any valid FastObjects base type. The literals are type-checked and must be of the same type as the class member. The compare-predicate is a boolean predicate because it always evaluates to either true or false. The boolean operators AND and OR can be used to construct arbitrarily complex conditions. The WHERE clause is optional. When a WHERE clause is not specified, the complete extent is returned. In the following example, the WHERE clause limits, or filters, the result-set to all objects in the extent that have a unitprice value greater than SELECT * FROM ProductExtent AS product WHERE product.unitprice > This query finds all products that cost more than Wildcards The wildcard character * represents zero, one, or more characters in the search string. Wildcard characters are used in string literals. When using wildcards, you must use the LIKE operator rather than =. The following example query uses a wildcard in the search string: SELECT product FROM ProductExtent AS product WHERE product.name LIKE "H*" This query finds all products with names starting with the letter H. 14

23 The WHERE Clause Boolean Operators AND, OR, and NOT Use the AND and OR keywords to specify multiple search criteria. Criteria can also be negated by using NOT. The following example uses the AND operator to combine two search criteria. SELECT product FROM ProductExtent AS product WHERE product.unitprice > AND product.unitprice <= ORDER BY product.unitprice This query finds all products that cost more than and less than or equal to The following example uses the OR operator. SELECT product FROM ProductExtent AS product WHERE product.unitprice <= OR product.untprice > ORDER BY product.unitprice This query finds all products that cost or less or The following example uses the NOT operator. SELECT product FROM ProductExtent AS product WHERE NOT(product.unitPrice <= 100.0) ORDER BY product.unitprice Standard Comparison Operators The following table shows the standard OQL comparison operators. The FastObjects OQL implementation adds two additional operators, == (equality) and <> (inequality). These are the same as the standard OQL operators = and!= respectively. These additional operators have been added to make comparison tests look more like C++ notation. 15

24 The WHERE Clause Table 2.1. Standard OQL Comparison Operators Operator = == LIKE NOT LIKE!= <> > >= < <= Function Equality Equality (FastObjects OQL extension) Equality (string argument with wildcard(s); refer to Section 2.3.1, Wildcards pg. 14) Does not match the wilcard pattern (refer to Section 2.3.1, Wildcards pg. 14) Inequality (not equal) Inequality (not equal, FastObjects OQL extension) Greater than Greater than or equal to Less than Less than or equal to In addition to the standard comparison operators, FastObjects OQL also provides comparison qualifiers for performing various comparisons Special Comparison Qualifiers FastObjects OQL provides special comparison qualifiers to support several non-standard comparison modes: case-insensitive text comparison, full-text comparison, ignore wildcards comparison, ignore whitespace comparison, ignore diacritics comparison, and ignore symbols comparison. The qualifiers are specified inside angle brackets (<>) that immediately follow the standard comparison operator (do not use blank spaces). The operators and qualifiers are used together in the WHERE clause.... WHERE extent.stringmember =<qualifier> "search string" Case-insensitive Comparisons A case-insensitive comparison compares strings without regard to the case (i.e., uppercase and lowercase) of the alphabetic characters (A Z, a z). In a case-sensitive comparison, the strings Windows Programming and windows programming would not be equal; in a case-insensitive 16

25 The WHERE Clause comparison, the two strings would be equal. The default mode of comparing strings is case-sensitive. To perform a case-insensitive comparison, you need to specify the =<ic> qualifier. The following example uses the case-insensitive comparison qualifier, =<ic>.... WHERE product.name =<ic> "windows programming" This example would find all products titled windows programming, Windows Programming, WINDOWS PROGRAMMING, etc. Database Must Use Indexing, Internationalization To use case-insensitive comparisons, the database must be created with the xi option (use internationalized strings and indexing). If the database is created without this option, the case-insensitive qualifier is ignored. Alternatively, you can use internationalization on a per-index basis. This is accomplished with the lexicalorder property of the FastObjects [Index] attribute. Full-Text Comparisons The FastObjects system supports indexing services, providing easy integration of alternate indexing structures. External index engines may be plugged into the FastObjects database system in order to provide specific indexing services. These external indexing engines are also referred to as full-text indexing services because large amounts of text are indexed. OQL queries can make use of these full-text indexing services. This is accomplished by using the full-text comparison qualifier with a full-text indexing specific <literal> string in the WHERE clause of a SELECT statement. The search criteria are then automatically passed to the full-text search engine. Full-text queries have their own syntax for specifying search criteria. The standard comparison operators (==), (!=), (<>), (>), (<), (>=), and (<=) are ignored; use the equality operator (=) combined with the <ft> qualifier. The comparison criteria specified in the full-text literal string are used as the query criteria. To perform a full-text comparison, you need to specify the full-text comparison qualifier. The following example uses the full-text comparison qualifier =<ft> in the WHERE clause.... WHERE product.synopsis_ =<ft> "index service specific query" In the example, "index service specific query" refers to a query clause as it would be stated in the syntax of the search engine being used. 17

26 The WHERE Clause Ignore Wildcards Comparisons The ignore wildcards qualifier, =<iw>, allows you to ignore any wildcards (asterisk and question mark) that may be present. Ignore Whitespaces Comparisons The ignore whitespace qualifier, =<is>, allows you to ignore any whitespaces (space, tab, carriage return, etc.) that may be present. Ignore Diacritics Comparisons The ignore diacritics qualifier, =<id>, allows you to ignore any diacritics that may be present. Ignore Symbols Comparisons The ignore symbols qualifier, =<iy>, allows you to ignore any symbols (such as [ or ) or -) that may be present Comparing null Object References If you want to search for an object or objects with an object reference that is set to null, you can use the nil keyword. The following example selects all Employee objects whose boss data-member is null. SELECT * FROM EmployeeExtent as e WHERE e.boss = nil The IN extent Clause The IN extent clause allows you to test for the presence of an object in a class extent (classnameextent or its alias). The object being tested must be a referenced object of the set-variable. The IN extent clause is used within the WHERE statement. The clause returns a boolean value, i.e., true or false. The following example query uses the IN extent clause. 18

27 The ORDER BY Clause SELECT * FROM ProductExtent as product WHERE product.supplier IN CompanyExtent This query selects the product if the product supplier is in the CompanyExtent If all products in the database have a reference to a Company object that is in the CompanyExtent, this query returns all products The ORDER BY Clause The ORDER BY clause specifies the sorting sequence used for the result-set. The sequence is specified as a list of members of the extents used in the FROM clause. You can specify whether the query uses ascending or descending order by using the keywords ASC or DESC respectively. If you do not specify the order, the default value is ascending. The first member name listed is the primary sequence. Additional member names, if used, specify secondary sort sequences. Specifying an ORDER BY clause may adversely affect the performance of a query. Extents can be indexed to optimize orderings that you often use. The FastObjects Query Optimizer automatically makes use of extent indexes when they exist. The ORDER BY keywords are as follows: ASC Ascending sort order DESC Descending sort order The following example query uses the ORDER BY clause. SELECT * FROM ProductExtent AS product ORDER BY product.unitprice ASC, product.name DESC In this example query, the result-set is first sorted by unit price in ascending order (primary sort order), then by name in descending order (secondary sort order). 19

28 The COUNT Statement 2.5. The COUNT Statement The COUNT statement is used in combination with a SELECT statement to find the number of objects that meet the query conditions of the WHERE clause. When no query conditions are specified (no WHERE clause), the total number of objects in the extent is returned. The COUNT statement always returns an integer as its result, representing the number of objects that meet the conditions of the query. The following examples describe the two basic methods for using the COUNT method with the SELECT statement. SELECT COUNT(*) FROM ProductExtent AS product WHERE product.unitprice > This query returns the number of products that cost more than COUNT ( SELECT * FROM ProductExtent AS product WHERE product.name LIKE "Dual*" ) This query returns the number of products whose name starts with the word Dual. Notice the use of the LIKE operator (refer to Section 2.3.1, Wildcards pg. 14) Using the COUNT Statement Within a WHERE Clause (nested SELECT statements are not yet implemented in the alpha version) The COUNT statement can be used as a query condition to the WHERE clause of a SELECT statement. A query condition based on a count is often called a counting condition. Counting conditions can be applied only to embedded collections. Both formats of the COUNT statement are supported inside the WHERE clause. 20

29 The COUNT Statement COUNT ( SELECT... ) and SELECT COUNT... Counting conditions are useful for providing selection criteria based on the number of elements in an embedded collection. If the WHERE clause is omitted from the counting condition, the total number of objects in the embedded collection is returned. An integer is always returned, representing the number of objects that meet the conditions of this sub-query. The following example uses the count of an embedded collection as a query condition. Notice that the COUNT statement does not have a WHERE clause of its own. Thus, the total number of elements in the embedded collection is always returned. SELECT order FROM OrderExtent AS order WHERE ( SELECT COUNT(*) FROM order.details ) > 1 This query finds all order with more than one order item. The next example provides a WHERE clause in the counting condition, which will limit the count based on the condition of the COUNT statement WHERE clause. This kind of counting condition is useful for finding the number of elements in an embedded collection based on a query condition. SELECT * FROM OrderExtent AS order WHERE COUNT( SELECT * FROM order.details AS detail WHERE detail.product.name LIKE "J*" ) >= 1 This query finds all orders with one or more order details referencing a product with a name that starts with J. (The LIKE operator is used with wildcard arguments. Refer to Section 2.3.1, Wildcards pg. 14.) 21

30 The COUNT Statement Counting conditions can be used in combination with other query conditions in a WHERE clause. If a WHERE clause becomes too lengthy, use parentheses to help readability. SELECT order FROM OrderExtent AS order WHERE ( COUNT ( SELECT * FROM order.details_ AS detail WHERE detail.product.name_ LIKE "J*" ) >= 1 ) AND ( order.orderno_ > 1000 ) Notice the use of the identifier order in the FROM part of the SELECT statement in the COUNT clause. It is important to use the same identifiers that you declared in the enclosing SELECT statement in the COUNT clause to take advantage of counting conditions. If you declare another variable in the FROM part of the second SELECT (part of the COUNT clause), the second query is treated as a stand-alone query, which is executed alone and is not used as a counting condition for the enclosing query. You need to be aware that this syntactical difference may lead to a totally different query than you intended. Compare the following two queries. SELECT order FROM OrderExtent AS order WHERE ( COUNT ( SELECT * FROM OrderExtent AS order, order.details_ AS detail WHERE detail.product.name_ LIKE "J*" ) >= 1 ) AND ( order.orderno_ > 1000 ) This query returns all orders with an order number larger than 1000 only if there are any orders in the database referencing products with names that start with J. SELECT order FROM OrderExtent AS order WHERE ( COUNT ( 22

31 The EXISTS and EXISTS IN Statements SELECT * FROM order.details AS detail WHERE detail.product.name_ LIKE "J*" ) >= 1 ) AND ( order.orderno_ > 1000 ) This query returns all orders with an order number larger than 1000 with one or more order items that reference a product with a name that starts with J. Also, consider this example query. Is the result really what you want? SELECT product FROM ProductExtent AS product WHERE ( COUNT ( SELECT * FROM CompanyExtent AS company WHERE company.name_ LIKE "M*" ) >= 1 ) AND ( product.unitprice > ) This query returns all products that cost more than if there are any companies in the database whose name starts with M The EXISTS and EXISTS IN Statements The EXISTS IN statement is used to test whether a query condition is satisfied in an extent. If one or more objects exist that meet the specified conditions in the compare-predicate, the statement returns true. If no objects are found that meet the conditions, the statement returns false. The following are two examples of the EXISTS method. EXISTS ( SELECT product FROM ProductExtent AS product WHERE product.name = "Zoom-and-Cut" ) 23

32 The EXISTS and EXISTS IN Statements This example returns true if a product named Zoom-and-Cut exists in the database. EXISTS product IN ProductExtent : product.name = "Boolean Beans" This example returns true if a product named Boolean Beans exists in the database Using the EXISTS Statement within a WHERE Clause The EXISTS statement can also be used as a query condition to the WHERE clause of a SELECT statement. EXISTS conditions can be applied only to embedded sets. The statement checks for the presence of any elements of an embedded set that meet the query condition(s). If one or more objects of the embedded set meet the specified conditions in the compare-predicate, the statement returns true. If no objects meet the conditions, the statement returns false. The following example shows the use of the EXISTS statement in a WHERE clause. SELECT * FROM OrderExtent AS order WHERE ( EXISTS detail IN order.details : detail.product.name LIKE "Micro*" ) This query finds all orders with at least one order detail referencing a product with a name that starts with Micro. EXISTS conditions can be used in combination with other query conditions in a WHERE clause. If a WHERE clause becomes too lengthy, use parentheses to help readability. Following is the same example, with the extra condition that the order has an order number greater than SELECT order FROM OrderExtent AS order WHERE ( EXISTS detail IN order.details : detail.product.name LIKE "Micro*" ) AND ( order.orderno > 1000 ) 24

33 The FOR ALL Statement This query finds all orders with an order number greater than 1000 and at least one order detail referencing a product with a name that starts with Micro The FOR ALL Statement The FOR ALL statement is used to test whether a query condition is true for every object in an extent. The statement returns true if all elements of the extent satisfy the query condition(s). If even one object in the extent does not satisfy the query condition, false is returned. FOR ALL product IN ProductExtent : product.unitprice > This example returns true if every product costs more than The DEFINE Statement The DEFINE statement allows you to simplify complicated queries by creating identifiers as synonyms for queries. Defining a query will not cause it to be performed. The query is executed only if it is used inside another active query statement. Queries can be nested in this manner, allowing you to define a query once and reuse it later. In the following example, the first statement defines a query named cheapproducts. The second statement, a SELECT statement, is actually executed. It uses the query defined in the first statement in its FROM clause. This causes the result-set of the first query to be used as the input to the second query. DEFINE cheapproducts AS SELECT * FROM ProductExtent AS product WHERE product.unitprice < 1.0; SELECT * FROM s IN nineties WHERE cheapproducts.name LIKE "Bug*" A query named cheapproducts is first defined and then used as input to the second query. This query returns the products with a title beginning with Bug that cost less that Compare with the following: 25

34 The ELEMENT Statement SELECT * FROM product IN ProductExtent WHERE product.name LIKE "Bug*" The query returns all products with a name beginning with Bug The ELEMENT Statement If a query returns only one item, you can convert the result from a collection to a single object using the ELEMENT operator. If the SELECT statement returns more than one object, the ELEMENT statement returns an error code and does not convert any objects. The ELEMENT statement is of greatest use for queries embedded in a programming language when you know that you will find exactly one object and when you know the type of the object. ELEMENT ( SELECT product FROM ProductExtent AS product WHERE product.name = "Bug Deleter" ) This query returns one product object Querying on Object Identity Each object in the database has a unique object identity, or OID. This OID can be used in defining filtering conditions for data-members of an object. That is, you can search for objects with a reference to a specific object by specifying the OID of the referenced object The Object Identifier OID This section provides a general discussion of object identifiers. For additional information about object identifiers and how they are formatted, refer to the FastObjects Programmer's Guide and API Reference. The following is a code fragment that retrieves and prints the identifier of an object. 26

35 Querying on Object Identity C# //... Product product = new Product( "Menu Factory" ); scope.add( product ); IObjectId id = scope.getobjectid( product ); System.out.println( "Menu Factory id: " + id ); //... This prints a line similar to the following: Menu Factory id: (0:1-2426#42,101) The object identifier (OID) consists of four parts. (Refer to the OID returned by the previous example (0:1-2426#42,101).) The first part of the identifier is the number of the database containing the object. Each database that is opened in an application has an identifying number. The database number is zero (0) in the example. The second part of the object identifier is the actual identification number, or surrogate, of the object in the database. It has two parts, a high-value (1 in the example) and a low-value (2426). The identification number remains the same for the life of the object. These numbers are not recycled, so every object, past and present, will be assigned a unique value for any given database. If the object has not yet been assigned, only the class ID will be meaningful. All other fields will be zero ( 0). The third part, following the # character, is the block address of the object in the database file. This value is subject to change. If the object grows or shrinks in size or if the database is reorganized, the database manager is free to relocate the object in the file. For this reason, the block ID is ignored for query comparison purposes. The last value is the identification number of the class type of the object in the dictionary. Every class definition in the associated dictionary of the database has a unique identifier. For example, the class ID for the Company class in the sample database is 102. You may also specify a class version number with the class ID. The version number is separated from the class ID by the letter v (e.g., 102v1 would refer to the second version of the Company class definition in the dictionary). If the version number is omitted (usually the case), the latest version is assumed. The components of the object identifier are summarized in the following table. Table 2.2. Components of the Object ID (dbid:hval-lval#blkid,classid) Database Object ID: 27

36 Querying on Object Identity Component dbid hval lval blkid classid Description Database identification in the application (may change depending on the order in which the databases are opened in the application). High-order bytes of the object surrogate (constant for the life of the object in the database). Low-order bytes of the object surrogate (constant for the life of the object in the database). Block address of the object in the database file (may change if the object is relocated in the database file). Class identifier (constant for the class in the dictionary) The OID in an OQL Query The object ID is actually stored in all persistent objects in FastObjects as a PtRef data-member. To query on the OID, you have to instruct the FastObjects OQL query engine to construct a PtRef with the desired OID. This PtRef object is then compared to find the desired object. There are two formats available for specifying an object identity in an OQL query. Both are essentially PtRef constructors. PtRef(0,0,3,34,102) PtRef("(0:0-3#34,102)") The following is an example query using an object OID. In this example, the database ID is 0. Consequently, this query will work only if the database being queried is the first one to be opened in a given application (this should be the case when using the FastObjects Developer's Workbench to work with the examples). The object ID, or surrogate, is 0-3. The block ID, 34, is ignored in the query. The class ID is 102, which is the ID of the Supplier class in the sample database. SELECT * FROM ProductExtent AS product WHERE product.supplier = PtRef(0,0,3,34,102) An object-identity (OID) is used to find all products that reference the Supplier object with object id 0-3 and class ID 102. Only objects referenced by the set-variable (data-members) may be queried using OIDs. 28

37 Additional Notes The following query will result in an error even though it refers to the same Supplier object as in the preceding example query. SELECT * FROM SuppierExtent AS suppier WHERE supplier = PtRef(0,0,3,34,102) Specifying the OID of the set-variable is not allowed. This will result in the error function not supported yet. When you enter a query by hand, object identities can be difficult to work with. Querying on object identities is usually done using embedded OQL, where you can use runtime replacement strings to insert an OID into the OQL statement Additional Notes This section provides information about casting and the DISTINCT keyword Casting Occasionally, you may find it necessary to use a cast operation in a query. Casting in OQL is similar to casting in your object oriented programming language. You can cast an object only to a related class, i.e., to a super-class (base class) or a to a sub-class (a derived class). Thus, you can cast a Product object to a Video ( Video is a sub-class of Product). But you cannot cast Product to an unrelated class such as, for example, Director. The following example shows a partial definition of the Video class. [Persistent] class Video : Product { //... Director director; //... }; 29

38 Additional Notes The Video class is derived from Product. Director is a class representing a film or video director and is not in the Product class hierarchy. The Video class has a Director data-member the base class, Product, does not. Now consider the following query. SELECT * FROM ProductExtent as product WHERE ((Video)product).director = "Stanley Kubrick" To query on the name of the director, you need to cast the set-variable, product, which is of type Product. If you attempt a cast that is illegal (such as casting Product to Director), the OQL engine will return the error type error: cast operator: class 'X' must be superclass or subclass of class 'Y' The DISTINCT Keyword FastObjects does not currently support the DISTINCT keyword (SELECT DISTINCT). However, you can often reword a query so that the DISTINCT keyword is unnecessary. Consider the following examples, in which the goal is to find the product categories with products cheaper than In this first example, you will receive a result-set of Category objects by specifying a path-expression in the initial SELECT clause. Then query the ProductExtent for the products with a unit price less than 1.0. The query places the categories of those products in the result-set. SELECT product.category FROM ProductExtent AS product WHERE product.unitprice < 1.0 Your result-set might contain, say, twenty elements. This means there are twenty products that cost less than But the result set contains Category objects and many of them would likely be repeated. By specifying a path-expression, you asked the query to make a reference to the category of the selected products in the result-set. There were twenty products, so there are twenty references to Category objects. 30

39 FastObjects OQL Warning and Error Codes Your original goal was to find the categories that have products that cost less than You succeeded with the last query, but what you most likely wanted was one result element for each category. In the full OQL semantics, you can achieve that by specifying that you want distinct result-set elements. Here is an example. SELECT DISTINCT product.category FROM ProductExtent AS product WHERE product.unitprice < 1.0 Don't use this! Because of the presence of the DISTINCT keyword, this query will return the error function not implemented in the FastObjects OQL implementation. You can rewrite this query so that you do not need the DISTINCT keyword. The following produces a result-set with the Category objects (just one each) which contain products with a unit price less than And you can use this in FastObjects. SELECT cat FROM CategoryExtent AS cat WHERE cat.products.unitprice < 1.0 Also, this query probably reads more like what you had in mind. By specifying a query on the CategoryExtent, you make it clear that you want Category objects in the result-set FastObjects OQL Warning and Error Codes This section presents the warning and error codes that FastObjects OQL queries may return Warning Codes The following table lists the warning codes that you may encounter when using the FastObjects OQL implementation. Warning codes have positive number values. Table 2.3. FastObjects OQL Warning Codes General Warnings 31