This chapter describes how to use the Oracle NoSQL Data Cartridge to integrate an Oracle NoSQL database into an Oracle Event Processing event processing network and query data from the database.
The Oracle NoSQL Database is a distributed key-value database. In it, data is stored as key-value pairs, which are written to particular storage node(s). Storage nodes are replicated to ensure high availability, rapid failover in the event of a node failure and optimal load balancing of queries.
The content in this guide assumes that you are already familiar with, and likely running, an Oracle NoSQL database. If you need more information about Oracle NoSQL, be sure to see its Oracle Technology Network page at http://www.oracle.com/technetwork/products/nosqldb/.
Note:
To use the NoSQL Data Cartridge, you must have a license for NoSQL Enterprise Edition.
This chapter includes the following sections:
You can use the Oracle Event Processing NoSQL Database data cartridge to refer to data stored in Oracle NoSQL Database as part of an Oracle CQL query. The cartridge makes it possible for queries to retrieve values from an Oracle NoSQL Database store by specifying a key in the query and then referring to fields of the value associated with the key.
When integrating an Oracle NoSQL database, keep the following guidelines in mind:
The NoSQL database must have been started through its own mechanisms and must be accessible. It is not managed directly by Oracle Event Processing.
This release of the cartridge provides access to the database using release 1.2.123 of the Oracle NoSQL Database API.
The property used as a key in queries must be of type String. Joins can use a single key only.
Joins must use the equals operator. Other operators are not supported in a join condition.
Run-away queries involving the NoSQL database are not supported.
To use the Oracle Event Processing NoSQL Database data cartridge in a CQL application, you must declare and configure it in one or more application-scoped cartridge contexts for the application.
Integrating an existing NoSQL database is similar to the way you might integrate a table from a relational database. For a NoSQL database, you update the EPN assembly file in the following ways (see Example 19-1, "EPN integrating a NoSQL Database"):
Add namespace declarations to support for the store element for referencing the NoSQL data source.
Your changes should add a namespace schema location to the schemaLocation attribute, along with a namespace and prefix declaration:
http://www.oracle.com/ns/oep/nosqldb http://www.oracle.com/ns/oep/nosqldb/oep-nosqldb.xsd
xmlns:nosqldb="http://www.oracle.com/ns/oep/nosqldb/"
Add the store element to integrate the NoSQL database into the event processing network as a relation source.
The store element supports the following attributes, all of which are required:
id -- The name that will be used to refer to the key-value store in CQL queries.
store-name -- The name of the key-value store, which should match the name specified in the KVStoreConfig class when creating the store.
store-locations -- One or more host names and ports of active nodes in the store. The attribute value is a space-separated list in which each entry is formatted as "hostname:port". Nodes with the specified host name and port values will be contacted in order when connecting to the store initially.
event-type -- The object type for all objects retrieved for this relation from values in the store. The attribute value should correspond to the name of a wlevs:event-type entry specified in a wlevs:event-type-repository entry.
Add a table-source element to connect the NoSQL database to the processor in which queries will be executed.
Example 19-1, "EPN integrating a NoSQL Database" illustrates how you can connect an event processing network to a NoSQL database. The store element provides access to a store named "kvstore-customers", using port 5000 on host kvhost-alpha or port 5010 on host kvhost-beta to make the initial connection. It defines Oracle CQL processor P1 and makes the data in the key-value store available to it as a relation named "CustomerDescription".
The store can be referred to within Oracle CQL queries using the name "CustomerDescription". All values retrieved from the store should be serialized instances of the CustomerDescription class.
Example 19-1 EPN integrating a NoSQL Database
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:osgi="http://www.springframework.org/schema/osgi"
xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
xmlns:nosqldb="http://www.oracle.com/ns/oep/nosqldb/"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/osgi
http://www.springframework.org/schema/osgi/spring-osgi.xsd
http://www.bea.com/ns/wlevs/spring
http://www.bea.com/ns/wlevs/spring/ocep-epn.xsd
http://www.oracle.com/ns/oep/nosqldb
http://www.oracle.com/ns/oep/nosqldb/oep-nosqldb.xsd">
<!-- Provide access to the CustomerDescription class, which represents
the type of values in the store. -->
<wlevs:event-type-repository>
<wlevs:event-type type-name="CustomerDescription">
<wlevs:class>com.bea.wlevs.example.CustomerDescription</wlevs:class>
</wlevs:event-type>
<wlevs:event-type type-name="SalesEvent">
<wlevs:class>com.bea.wlevs.example.SalesEvent</wlevs:class>
</wlevs:event-type>
</wlevs:event-type-repository>
<!-- The store element declares the key-value store, along with the
event type to which incoming NoSQL data will be bound. -->
<nosqldb:store store-name="kvstore-customers"
store-locations="kvhost-alpha:5000, kvhost-beta:5010"
id="CustomerDescription"
event-type="CustomerDescription"/>
<wlevs:channel id="S1" event-type="SalesEvent">
<wlevs:listener ref="P1"/>
</wlevs:channel>
<!- The table-source element links the store to the CQL processor. -->
<wlevs:processor id="P1">
<wlevs:table-source ref="CustomerDescription" />
</wlevs:processor>
</beans>
The event types defined in Example 19-1, "EPN integrating a NoSQL Database" are implemented as JavaBeans classes as described in "Defining and Using Event Types" in Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
If Oracle CQL queries refer to entries in a store specified by a store element, then the values of those entries must be serialized instances of the type specified by the event-type attribute. The event type class must implement java.io.Serializable.
If a query retrieves a value from the store that is not a valid serialized form, or if the value is not the serialized form for the specified class, then Oracle Event Processing throws an exception and event processing is halted. You can declare multiple store elements to return values of different types from the same or different stores.
After you have integrated a NoSQL database into an event processing network, you can access data from Oracle CQL code. The query can look up an entry from the store by specifying an equality relation in the query's WHERE clause.
In the Oracle CQL code shown in Example 19-2, "Oracle CQL Query Using Data from a NoSQL Database", the CustomerDescription in the FROM clause corresponds to the id attribute value in the store element shown in Example 19-1, "EPN integrating a NoSQL Database".
Example 19-2 Oracle CQL Query Using Data from a NoSQL Database
<n1:config
xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/application wlevs_application_config.xsd"
xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<processor>
<name>P1</name>
<rules>
<query id="q1"><![CDATA[
SELECT customerName, creditScore, price, item
FROM S1 [Now], CustomerDescription as cust
WHERE S1.userId = cust.userId
AND creditScore 5
]]></query>
</rules>
</processor>
</n1:config>
In this example, the event type instances representing data from the S1 channel and CustomerDescription NoSQL data source are both implemented as JavaBeans classes as described in "Defining and Using Event Types" in Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse. Because both event types are JavaBeans classes, the Oracle CQL query can access the customer description associated with a particular event by equating the event's user ID with that of the customer description in the WHERE clause, treating both as JavaBeans properties:
WHERE S1.userId = CustomerDescription.userId
This clause requests that an entry be retrieved from the store that has the key specified by the value of the event's userId field. Only equality relations are supported for obtaining entries from the store.
Once an entry from the store has been selected, fields from the value retrieved from the store can be referred to in the SELECT portion of the query or in additional clauses in the WHERE clause.
The creditScore value specified in the SELECT clause will include the value of the creditScore field of the CustomerDescription object retrieved from the store in the query output. The reference to creditScore in the WHERE clause will also further restrict the query to events where the value of the CustomerDescription creditScore field is greater than 5.
The key used to obtain entries from the store can be formatted in one of two ways: by beginning the value with a forward slash ('/') or by omitting a slash.
If the value specified on the left hand side of the equality relation starts with a forward slash, then the key is treated as a full key path that specifies one or more major components, as well as minor components if desired. For more details on the syntax of key paths, see the information about the oracle.kv.Key class in the Oracle NoSQL Database API documentation at http://docs.oracle.com/cd/NOSQL/html/javadoc/index.html.
For example, if the userId field of a SalesEvent object has the value "/users/user42/-/custDesc", then that value will be treated as a full key path that specifies "users" as the first major component, the user ID "user42" as the second major component, and a minor component named "custDesc".
As a convenience, if the value specified on the left hand side of the equality relation does not start with a forward slash, then it is treated as a single major component that comprises the entire key.
Note that keys used to retrieve entries from the store must be specified in full by a single field accessed by the Oracle CQL query. In particular, if a key path with multiple components is required to access entries in the key-value store, then the full key path expression must be stored in a single field that is accessed by the query.