Using Named Schemas

Contents

Using Named Schemas in EventFlow Applications
Using a Named Schema to Define Another Schema
Defining a Named Schema in the Definitions Tab
Importing a Named Schema
Promoting a Private Schema to a Named Schema
Using Named Schemas in StreamSQL Applications
Referencing Named Schemas in Expressions
Related Topics

You can define schemas as named objects that have module scope. Named schemas and their fields can be referenced in any component that takes a schema. By contrast, unnamed schemas, called private or anonymous schemas, are accessible only to connected downstream components in the application flow.

Table schemas are a form of named schema for Query Tables that includes a definition for the primary and secondary indices of the table, in addition to the fields of the table. Table schemas are described on Using Table Schemas.

Using Named Schemas in EventFlow Applications

A named schema effectively becomes a new data type for the module in which it is defined or imported. The following sections describe how to create and use named schemas in EventFlow applications:

Once you have defined a named schema, you can use it in the Edit Schema tab of the Properties view of any component that requires a schema. This includes:

In all input streams
When using the declared schema feature of output streams
In all Query Table data constructs
In all Lock Set data constructs
In the Union operator, when the Union Settings property specifies Require this Schema.
In the Field Serializer global Java operator
In the Edit Schema tab of many input and output adapters

Using a Named Schema to Define Another Schema

Once a named schema is defined for a module, the name is added to the drop-down list at the top of Edit Schema table (and to the list of data types) in other components in the same module (or in a referenced module). You can apply a named schema in two ways:

You can replace the entire schema of a component with the fields defined in a named schema. To do so, select the name of the named schema from the drop-down list at the top of the Fields table. This pulls the field definitions of the named schema into the current Fields table, replacing any private field definitions already there.

Thereafter, the Fields table shows the read-only contents of the named schema. If you change the definition of the named schema in the Definitions tab of the EventFlow Editor, the changes are automatically propagated to all Fields tables that specify the same named schema.
You can define the fields of an individual tuple field with a named schema. To do so, select the name of the named schema in the Type column's drop-down list. In the following example, the component has a private schema with three fields. The third field, IncomingTuple, has data type tuple, and its fields are defined as an instance of the NYSE_FeedSchema named schema.

Defining a Named Schema in the Definitions Tab

In EventFlow applications, you can create and view named schemas in the Constants, Named Schemas, and Table Schemas section of the Definitions tab of the EventFlow Editor. To create a named schema:

Open the Definitions tab.
Click the Add Named Schema button.
In the Edit Saved Schema dialog, enter a schema name.

Populate the schema fields using one of these methods:

Define the schema's fields manually, using the Add button at the top of the tab to add a row for each schema field. Enter values for the Field Name and Type. The Description cell is optional. For example:

Field Name	Type	Description
symbol	string	Stock symbol
quantity	int	Number of shares

Field names must begin with an alphabetic character or an underscore, can contain only alphabetic characters, numbers, and underscores, and cannot contain hyphens or other special characters. The data type must be one of the supported StreamBase Data Types, or, for a tuple field, the identifier of a named schema.

Reuse an existing schema whose fields are appropriate for this component. The existing schema can be a schema that you previously saved, one that you imported from your file system (as described in Importing and Exporting Resources), or one that exists in another application in your workspace. To reuse an existing schema, click the Copy Schema button. If prompted to save the application before continuing, click Yes.

In the Copy Schema dialog, identify the schema of interest. See Copying Schemas for details.

The schema fields are loaded into the schema table.

Tip

You can also drag a saved schema from the Saved Schemas view and drop it onto the schema table in the Schema tab. If you already have entries in the table, StreamBase prompts for permission to replace them with the contents of the schema you are copying.

Use the Remove, Move Up, and Move Down buttons to edit and order your schema fields. If you have copied a schema, remember that this is a local copy and any changes you make here do not affect the original schema that you copied.

Click OK to add the schema.

The new schema is added to the tree list of named schemas. You can manage items in the list using either the buttons or context menu commands.

Importing a Named Schema

You can import a named schema defined in another module to the current module. Use the Manage Module Imports section of the Definitions tab of the EventFlow Editor.

You can import a named schema from:

Another module in the same project.
A module in another project in the current project's Module Search Path.

Promoting a Private Schema to a Named Schema

You can create a named schema by promoting the existing private schema of a schema-bearing component as a named schema, accessible in the Definitions tab for the current module. Schema-bearing components that can promote their schemas to named include: input streams, output streams with declared schemas, connection arcs, Union operators with declared schemas, Query Tables, and the Lock Set data construct. Follow these steps:

Select the component in the canvas that carries the schema of interest.
Right-click and select Schema → Refactor to Named Schema from the context menu.
In the Promote to Named Schema dialog:
1. The Name field shows a suggested name for the named schema, generated from the selected component's canvas name plus "Schema". Edit this suggestion to reflect your site's naming standards, or leave it in place to accept the suggested name.
2. The Preview section shows the schema of the selected component.
3. The checkbox for Refactor other components in this module using this same schema is checked by default. This directs StreamBase to locate other components in the current module that use a private schema with the exact same field names, data types, and field order as shown in the Preview section. If any such components are located, StreamBase converts them from using that private schema to using the equivalent named schema.
  
  Uncheck this checkbox to create a named schema without applying it to any component other than the current one. (Unchecking also disables the Next button.)
If you leave the Refactor other components checkbox checked, the Next button remains active. Click Next to see the second page of the dialog.

You can also press Finish to complete the dialog now. In this case, Studio applies this named schema to all components found with the same schema in the current module.
Use the second page of the dialog to narrow the list of other components to which you want the named schema applied. The second page shows a list of schema-bearing component categories. If there are any component candidates in the current module that use the same schema, they are shown in the list. Use the checkboxes to select the components to which you want the named schema applied.

If all the checkboxes are disabled (or if the Select All and Deselect All buttons have no effect), then StreamBase did not locate any components with matching schemas in the current module.
Click Finish to create and apply the named schema.
To add documentation for the named schema or for any of its fields, open the Definitions tab of the EventFlow Editor, select the newly added named schema entry, and click Edit. Fill in the Schema Description field and the Description column for each field as required.

Using Named Schemas in StreamSQL Applications

Use the CREATE SCHEMA keyword in StreamSQL to declare a named schema. In the following example, we create a schema named point, and then define the schema of an input stream named instream whose schema has two fields. The first field is named tag, and has type string; the second field is named p and has type tuple. The schema of tuple p is defined as the schema named point.

CREATE SCHEMA point(x double, y double);
CREATE INPUT STREAM instream (tag string, p point);

See CREATE SCHEMA Statement in the StreamSQL Guide for more on declaring named schemas in StreamSQL applications. After declaring a named schema, you can use it in the schema declarations of:

You can reference a named schema and its fields in the same StreamSQL constructs that reference unnamed (anonymous) schemas, as described in SELECT Statement.

Referencing Named Schemas in Expressions

In EventFlow applications, the name of a named schema is analogous to the name of the data type tuple. Use the named schema's name where you would use tuple, when defining the schema of a tuple field.

When using a named schema to define the tuple of a nested tuple field, use the name of the field, not the name of the schema, to resolve the names of sub-tuple fields. The following image shows an Fields table where a three-field tuple is defined as a private schema. The third field has type tuple, and its schema is defined with the named schema NYSE_FeedSchema.

In this case, the name of the fourth field of the IncomingTuple field resolves to IncomingTuple.bid_size for use in expressions. Do not use the name of the named schema as any part of field name resolution. For example, the identifier NYSE_FeedSchema.bid_size has no meaning and cannot be used in any expression.

A new function in the StreamBase expression language is automatically generated by syntactic sugar for every named schema. The function's name is the name of the named schema, and it takes one or more comma-separated arguments, whose values must be compatible with the data types of the named schema. For example, for the named schema point, whose schema is (x double, y double), you can use the following expression in a component anywhere in the module that defines point:

point(32.0, 44.5)

If you use the name of a named schema with no arguments, it creates a null tuple whose schema is that of the named schema. This is analogous to using the Set null checkbox for a field of type tuple in the Manual Input view in StreamBase Studio.

point()

See tuple for more on using tuple data in expressions.