The Runtime Schema Cast operator casts its input schema to its configured target output schema at run time. This operator is used in nested modules to expand the subfields within a capture field, either by flattening or nesting the captured subfields. Flattened subfields appear as top-level fields of the target schema, while nested fields appear as subfields of a top-level tuple field whose name matches that of the captured field.
This operator is likely to be used in modules that use capture fields in their input schema or table definitions. Such modules serve as generic interface modules that are transformed at run time into specific uses.
For example, the OrderMatcher.sbapp module in the Capture Fields and Parent Schemas sample can be used to process orders using any financial instrument type. The TopLevelFX.sbapp module in that sample calls the Order Matcher module in a way that processes orders for FX trades. In this example as delivered,
there is no need for a Runtime Schema Cast Operator.
Now consider a different Order Matcher module, perhaps named OrderMatcherWithSpecialHandling.sbapp that handles orders generically for all instrument types, but also has special handling for FX orders. Inside such a module,
processing might be split into two branches, one for FX orders, the other for all other order types. The FX processing branch
could start with a Runtime Schema Cast Operator that extracts the capture field data from the module's input stream, using
either FLATTEN or NEST transform strategy. See Client Access to Capture Fields.
This section describes the properties you can set for a runtime schema cast operator, using the various tabs of the Properties view in StreamBase Studio.
This section describes the properties on the General tab in the Properties view for the Runtime Schema Cast operator.
Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Operator: A read-only field that shows the formal name of the operator.
Class: A field that shows the fully qualified class name that implements the functionality of this operator. Use this class name when loading the operator in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this operator starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the operator does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
This section describes the properties on the Operator Properties tab in the Properties view for the Runtime Schema Cast operator.
| Property | Description |
|---|---|
| Capture Transform Strategy | Set to FLATTEN to have captured fields appear as top-level fields of the output schema and NEST to have captured fields appear as subfields of a top-level tuple field.
|
For the Runtime Schema Cast operator, use the Edit Schema tab to specify the schema of the operator's output port. The schema must match the input schema after being transformed as specified by the Capture Field Strategy property. Since the transformation occurs at runtime, errors in specifying the output schema are detected at runtime and cause the operator to fail to start.
Use the Edit Schemas tab much like other Edit Schemas tabs throughout StreamBase Studio:
-
Use the control at the top of the Edit Schemas tab to specify the schema type:
- Named schema
-
Use the drop-down list to select the name of a named schema previously defined in or imported into this module. The drop-down list is empty unless you have defined or imported at least one named schema for the current module.
When you select a named schema, its fields are loaded into the schema grid, overriding any schema fields already present. Once you import a named schema, the schema grid is dimmed and can no longer be edited. To restore the ability to edit the schema grid, re-select
Private Schemafrom the drop-down list. - Private schema
-
Populate the schema fields using one of these methods:
-
Define the schema's fields manually, using the
button to add a row for each schema field. You must enter values for the Field Name and Type cells; the Description cell
is optional. For example:
Field Name Type Description symbol string Stock symbol quantity int Number of shares Field names must follow the StreamBase identifier naming rules. The data type must be one of the supported StreamBase data types, including, for tuple fields, the identifier of a named schema and, for override fields, the data type name of a defined capture field.
-
Add and extend a parent schema. Use the
button's Add Parent Schema option to select a parent schema, then optionally add local fields that extend the parent schema. If the parent schema includes
a capture field used as an abstract placeholder, you can override that field with an identically named concrete field. Schemas
must be defined in dependency order. If a schema is used before it is defined, an error results.
-
Copy an existing schema whose fields are appropriate for this component. To reuse an existing schema, click the
button. (You may be prompted to save the current module before continuing.)
In the Copy Schema dialog, select the schema of interest as described in Copying Schemas. Click when ready, and the selected schema fields are loaded into the schema grid. Remember that this is a local copy and any changes you make here do not affect the original schema that you copied.
The existing schema can be from a system stream, or from any named or unnamed schema defined in the current module or in another application in your workspace. You can also select a CSV text file and populate a schema with its column headers. Studio will attempt to infer data types from the first few rows of values, and you can override the types it identifies. Currently, auto-detection of int, double, boolean, string, timestamp and tuples are supported, but not lists or functions. When indicating tuples, the CSV header must identify subtuples with dot notation, for example as
stock.symbol,stock.price.
Use the , , and buttons to edit and order your schema fields.
-
-
Optionally, document your schema in the Schema Description field.
Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.
Caution
Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.
The operator has one input port and one output port to communicate with the surrounding application. The input port's schema is expected to have a capture field. The output port's schema is a transformation of the input schema, with the captured fields appearing as either top-level or nested fields, depending upon the Capture Field Strategy property value.
The Runtime Schema Cast operator fails to start if the transformed input schema does not match the schema specified in the Target Output Schema property.