Adding Queries to a Class
InterSystems® Studio has been deprecatedOpens in a new tab. Beginning with version 2024.2, it is no longer included with installations of InterSystems IRIS®, and it is no longer receiving maintenance updates. An upgrade to InterSystems IRIS 2024.2 or later will remove any Studio installation which is associated with the instance.
The version of InterSystems Studio which was included with InterSystems IRIS 2024.1 is available as a stand-alone component from the WRC Downloads page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab). To show only the Studio downloads, type studio in the Name column. Neither upgrades nor new installations of InterSystems IRIS will affect a stand-alone Studio installation.
InterSystems provides the following documentation about Studio 2024.1 for legacy support only. InterSystems recommends that all users develop ObjectScript code using the InterSystems ObjectScript Extension Pack for Visual Studio Code. See Migrate from Studio.
InterSystems IRIS® class definitions may contain query definitions.
For an introduction, see Defining and Using Class QueriesOpens in a new tab. For details, see Query DefinitionsOpens in a new tab 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 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):
(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.
(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).
(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 DocumentationOpens in a new tab 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 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, , and down arrows, , 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")
{
}
}