Adding Queries to a Class

InterSystems IRIS® class definitions may contain query definitions.

For an introduction, see Defining and Using Class Queries in Defining and Using Classes. For details, see Query Definitions in the Class Definition Reference.

You can add a new query to a class definition in two ways:

Edit the class definition using the Class Editor.
Use the New Query wizard.

To add a query using the Class Editor, position the cursor on a blank line in the Class Editor and enter a query declaration such as:

Class MyApp.Person Extends %Persistent
{
Property Name As %String;

/// This query provides a list of persons ordered by Name.
Query ByName(ByVal name As %String) As %SQLQuery(CONTAINID = 1)
{
    SELECT ID,Name FROM Person
    WHERE (Name %STARTSWITH :name)
    ORDER BY Name
}

}

Alternatively, you can copy and paste an existing query declaration and then edit it.

New Query Wizard

You can use the New Query wizard to add a new query to a class definition. You can open the New Query wizard by selecting Class > Add > Query. Alternatively, right-click the Class Inspector and select Add > New Query. You can also click the New Query button rectangle with purple shading in the toolbar.

Select Finish at any time; default values are provided for any information you have not specified.

Name, Implementation, and Description Page

The New Query wizard prompts you for the following information (you can later modify any of these values):

Query Name

(required) Name of the new query. This name must be a valid query name and must not conflict with the name of a previously defined query.

See Rules and Guidelines for Identifiers.

Implementation

(required) You must specify if this query is based on an SQL statement (which the wizard generates for you) or on user-written code (in which case you have to provide the code for the query implementation).

Description

(optional) Description of the new query. This description is used when the class documentation is displayed in the online class library documentation.

A description may include HTML formatting tags. See Creating Class Documentation in Defining and Using Classes.

Input Parameters Page

A query may take zero or more input parameters (arguments).

You can specify the names, types, and default values for these parameters. The arguments are displayed in order in a table. You can add a new item to the argument list using the Add icon outline of square with yellow starburst located on the side of the table. This displays a popup dialog allowing you to specify the name of the argument, its type, its optional default value. Using up, up arrow icon , and down arrows, down arrow icon , you can rearrange the order of items in the list.

Columns Page

For an SQL-based query, you must specify the object properties (columns) that you want included in the result set (this is the SELECT clause of the generated SQL query).

To add a column to the query, select an item from the left-hand list of available properties and move it to the right-hand list using the > (Move To) button. You can also move the properties by double-clicking them.

Conditions Page

For an SQL-based query, you can specify conditions to restrict the result set (the SQL WHERE clause of the generated SQL query).

You can build a set of conditions by selecting values from the set of combo boxes. The expression box can contain an expression (such as a literal value) or a query argument (as an SQL host variable with a prepended : colon character).

Order By Page

For an SQL-based query, you can specify any columns you want to use to sort the result set (the SQL ORDER BY clause of the generated SQL query).

Row Specification Page

For a user-written query, you must specify the names and types of the columns that are to be returned by the query.

The wizard does not prompt for this information for SQL-based queries as the class compiler can determine it by examining the SQL query.

Results of Running the New Query Wizard

After you run the New Query wizard, the Class Editor window is updated to include the new query definition. For example:

/// This is a Person class
class MyApp.Person extends %Persistent 
{

Query ByName(ByVal name As %String) As %SQLQuery(CONTAINID = 1)
{
    SELECT ID,Name FROM Person
    WHERE (Name %STARTSWITH :name)
    ORDER BY Name
}

}

If you want to make further modifications to this query you can do this using either the Class Editor or the Class Inspector.

If you specified a user-written query, the Class Editor contains both the new query definition as well as skeletons of the query methods you are expected to implement. For example:

Class MyApp.Person Extends %Persistent 
{
// ...

ClassMethod MyQueryClose(
        ByRef qHandle As %Binary
        ) As %Status [ PlaceAfter = MyQueryExecute ]
{
    Quit $$$OK
}

ClassMethod MyQueryExecute(
        ByRef qHandle As %Binary,
        ByVal aaa As %Library.String
        ) As %Status
{
     Quit $$$OK
}

ClassMethod MyQueryFetch(
        ByRef qHandle As %Binary,
        ByRef Row As %List,
        ByRef AtEnd As %Integer = 0
        ) As %Status [ PlaceAfter = MyQueryExecute ]
{
    Quit $$$OK
}

Query MyQuery(
        ByVal aaa As %Library.String
        ) As %Query(ROWSPEC = "C1,C2")
{
}

}

Adding Indices to a Class

Adding Relationships to a Class