Oracle R Enterprise provides datastores that you can use to save Oracle R Enterprise proxy objects, as well as any R object, in an Oracle database. You can grant or revoke read privilege access to a datastore for one or more users. You can restore the saved objects in another R session. The objects in a datastore are also accessible to embedded R execution through both the R and the SQL interfaces.
This section describes the Oracle R Enterprise functions that you can use to create and manage datastores. The section contains the following topics:
With Oracle R Enterprise datastores, you can save R objects in the database.
R objects, including Oracle R Enterprise proxy objects, exist for the duration of the current R session unless you explicitly save them. The standard R functions for saving and restoring R objects, save and load, serialize objects in R memory to store them in a file and deserialize them to restore them in memory. However, for Oracle R Enterprise proxy objects, those functions do not save the database objects associated with the proxy objects in an Oracle database; therefore the saved proxy objects do not behave properly in a different R session.
You can save Oracle R Enterprise proxy objects, as well as any R object, with the ore.save function. The ore.save function specifies an Oracle R Enterprise datastore. A datastore persists in the database when you end the R session. The datastore maintains the referential integrity of the objects it contains. Using the ore.load function, you can restore in another R session the objects in the datastore.
Using a datastore, you can do the following:
Save Oracle R Enterprise and other R objects that you create in one R session and restore them in another R session.
Pass arguments to R functions for use in embedded R execution.
Pass objects for use in embedded R execution. You could, for example, use a function in the OREdm package to build an Oracle Data Mining model and save it in a datastore. You could then use that model to score data in the database through embedded R execution. For an example of using a datastore in an embedded R execution function, see Example 6-10.
The following table lists the functions that manipulate datastores and provides brief descriptions of them.
Table 2-1 Functions that Manipulate Datastores
| Function | Description |
|---|---|
|
|
Lists information about a datastore in the current Oracle database schema. |
|
|
Provides detailed information about the specified datastore in the current Oracle database schema. |
|
|
Deletes a datastore from the current Oracle database schema. |
ore.grant |
Grants read access to a datastore. |
|
|
Lazily restores objects from a datastore into an R environment. |
|
|
Restores objects from a datastore into an R environment. |
ore.revoke |
Revokes read access to a datastore. |
|
|
Saves R objects in a new or existing datastore. |
See Also:
"Using Oracle R Enterprise Embedded R Execution" for information on using the R and the SQL interfaces to embedded R execution
Each database schema has a table that stores named Oracle R Enterprise datastores. A datastore can contain Oracle R Enterprise objects and standard R objects.
You create a datastore with the ore.save function. When you create a datastore, you specify a name for it. You can save objects in one or more datastores.
As long as a datastore contains an Oracle R Enterprise proxy object for a database object, the database object persists between R sessions. For example, you could use the ore.odmNB function in the OREdm package to build an Oracle Data Mining Naive Bayes model. If you save the resulting ore.odmNB object in a datastore and end the R session, then Oracle Database does not delete the Oracle Data Mining model. If no datastore contains the ore.odmNB object and the R session ends, then the database automatically drops the model.
The ore.save function saves one or more R objects in the specified datastore.
By default, Oracle R Enterprise creates the datastore in the current user schema. With the arguments to ore.save, you can provide the names of specific objects, or provide a list of objects. You can specify whether read privilege access to the datastore can be granted to other users. You can specify a particular R environment to search for the objects you would like to save. The overwrite and append arguments are mutually exclusive. If you set the overwrite argument to TRUE, then you can replace an existing datastore with another datastore of the same name. If you set the append argument to TRUE, then you can add objects to an existing datastore. With the description argument, you can provide some descriptive text that appears when you get information about the datastore. The description argument has no effect when used with the append argument.
Example 2-18 Saving Objects and Creating a Datastore
This example demonstrates creating datastores using different combinations of arguments.
# Create some R objects.
df1 <- data.frame(x1 = 1:5, y1 = letters[1:5])
df2 <- data.frame(x2 = 5:1, y2 = letters[11:15])
iris_of <- ore.push(iris)
# Create a database table and an Oracle R Enterprise proxy object for the table.
ore.drop("AIRQUALITY")
ore.create(airquality, table = "AIRQUALITY")
# List the R objects.
ls()
# List the Oracle R Enterprise proxy objects.
ore.ls()
# Save the proxy object and all objects in the current workspace environment
# to the datastore named ds1 and supply a description.
ore.save(AIRQUALITY, list = ls(), name = "ds1", description = "My private datastore")
# Create some more objects.
x <- stats::runif(20) # x is an object of type numeric.
y <- list(a = 1, b = TRUE, c = "hoopsa")
z <- ore.push(x) # z is an object of type ore.numeric.
# Create another datastore.
ore.save(x, y, name = "ds2", description = "x and y")
# Overwrite the contents of datastore ds2.
ore.save(x, name = "ds2", overwrite = TRUE, description = "only x")
# Append object z to datastore ds2.
ore.save(z, name = "ds2", append = TRUE)
Listing for This Example
R> # Create some R objects.
R> df1 <- data.frame(x1 = 1:5, y1 = letters[1:5])
R> df2 <- data.frame(x2 = 5:1, y2 = letters[11:15])
R> iris_of <- ore.push(iris)
R>
R> # Create a database table and an Oracle R Enterprise proxy object for the table.
R> ore.drop("AIRQUALITY")
R> ore.create(airquality, table = "AIRQUALITY")
R>
R> # List the R objects.
R> ls()
[1] "df1" "df2" "iris_of"
R>
R> # List the Oracle R Enterprise proxy objects.
R> ore.ls()
[1] "AIRQUALITY"
R>
R> # Save the proxy object and all objects in the current workspace environment
R> # to the datastore named ds1 and supply a description.
R> ore.save(AIRQUALITY, list = ls(), name = "ds1", description = "My datastore")
R>
R> # Create some more objects.
R> x <- stats::runif(20) # x is an object of type numeric.
R> y <- list(a = 1, b = TRUE, c = "hoopsa")
R> z <- ore.push(x) # z is an object of type ore.numeric.
R>
R> # Create another datastore.
R> ore.save(x, y, name = "ds2", description = "x and y")
R>
R> # Overwrite the contents of datastore ds2.
R> ore.save(x, name = "ds2", overwrite = TRUE, description = "only x")
R>
R> # Append object z to datastore ds2.
R> ore.save(z, name = "ds2", append = TRUE)
With the ore.grant and ore.revoke functions you can grant or revoke access to an Oracle R Enterprise datastore.
With the ore.grant and ore.revoke functions, you can control access to datastores. You can grant read access to a specified user to a datastore that you own or revoke the access privilege. The functions ore.save, ore.load, ore.datastore, and ore.datastoreSummary have arguments related to the accessibility of datastores.
Note:
If you use ore.create to create a persistent database table and its proxy ore.frame object, then save the proxy ore.frame object in a grantable datastore, and then use ore.grant to grant read privilege access to the datastore, the access applies only to the ore.frame object. The read access does not extend to the persistent database table. To grant read permission to the table itself, you must execute an appropriate SQL command.
Example 2-19 Granting and Revoking Access to a Datastore
This example pushes the airquality data set from the local R session to the Oracle database, where it exists as the ore.frame object AIRQUALITY and as a temporary database table with the same name. The example then saves the AIRQUALITY object to the datastore ds3 and specifies that access to the datastore can be granted to other users. It invokes function ore.datastore with type = grantable to display all of the datastores to which read access has been granted. It grants the read privilege for the ds3 datastore to SCOTT. It then invokes ore.datastore with type = grant to display the datastores to which read access has been granted. It revokes the read privilege for SCOTT, and again displays the datastores to which access has been granted.
AIRQUALITY <- ore.push(airquality)
ore.save(AIRQUALITY, name = "ds3",
description = "My datastore 3", grantable = TRUE)
ore.datastore(type = "grantable")
ore.datastore(type = "grant")
ore.grant("ds3", type = "datastore", user = "SCOTT")
ore.datastore(type = "grant")
ore.revoke("ds3", type = "datastore", user = "SCOTT")
ore.datastore(type = "grant")
Listing for This Example
R> AIRQUALITY <- ore.push(airquality)
R> ore.save(AIRQUALITY, name = "ds3",
+ description = "My datastore 3", grantable = TRUE)
R> ore.datastore(type = "grantable")
datastore.name object.count size creation.date description
1 ds3 1 1451 2015-11-30 18:48:25 My datastore 3
R> ore.datastore(type = "grant")
[1] datastore.name grantee
<0 rows> (or 0-length row.names)
R> ore.grant("ds3", type = "datastore", user = "SCOTT")
R> ore.datastore(type = "grant")
datastore.name grantee
1 ds3 SCOTT
R> ore.revoke("ds3", type = "datastore", user = "SCOTT")
R> ore.datastore(type = "grant")
[1] datastore.name grantee
<0 rows> (or 0-length row.names)
You can get information about a datastore in the current user schema by using the ore.datastore and ore.datastoreSummary functions.
Using the ore.datastore function, you can list basic information about datastores. To get information about a specific type of datastore, you can use the optional character string type argument. The valid values for typeare the following:
user, which lists the datastores created by current session user. This is the default value.
private, which lists the datastores for which read access cannot be granted by the current session user to other users.
all, which lists all of the datastores to which the current session user has read access.
grantable, which lists the datastores the read privilege for which can be granted by the current session user to other users.
grant, which lists the datastores the read privilege for which has been granted by the current session user to other users.
granted, which lists the datastores the read privilege for which has been granted by other users to the current session user.
If you do not specify a type, then function ore.datastore returns a data.frame object with columns that correspond to the datastore name, the number of objects in the datastore, the datastore size, the creation date, and a description. Rows are sorted by column datastore.name in alphabetical order. If you do specify a type, then the function returns a data.framethat has a column for the specified type.
You can search for a datastore by name or by using a regular expression pattern.
The ore.datastoreSummary function returns information about the R objects saved within a datastore in the user schema in the connected database. The function returns a data.frame with columns that correspond to object name, object class, object size, and either the length of the object, if it is a vector, or the number of rows and columns, if it is a data.frame object. It takes one required argument, the name of a datastore, and has an optional argument, the owner of the datastore.
Example 2-20 Using the ore.datastore Function
This example demonstrates using the ore.datastore function.
# Create some R objects.df1 <- data.frame(x1 = 1:5, y1 = letters[1:5])
df2 <- data.frame(x2 = 5:1, y2 = letters[11:15])
iris_of <- ore.push(iris)
# Create a database table and an Oracle R Enterprise proxy object for the table.
ore.drop("AIRQUALITY")
ore.create(airquality, table = "AIRQUALITY")
# Save the objects to a datastore named ds1 and supply a description.
ore.save(AIRQUALITY, list = ls(), name = "ds1", description = "My private datastore")
# Create some more objects.
x <- stats::runif(20) # x is an object of type numeric.
y <- list(a = 1, b = TRUE, c = "hoopsa")
z <- ore.push(x) # z is an object of type ore.numeric.
# Create other datastores.
ore.save(x, y, name = "ds2", description = "x and y")
ore.save(df1, df2, name = "dfobj", description = "df objects")
ore.save(x, y, z, name = "another_ds", description = "For pattern matching")
# List all of the datastore objects.
ore.datastore()
# List the specified datastore.
ore.datastore("ds1")
# List the datastore objects with names that include "ds".
ore.datastore(pattern = "ds")
Listing for This Example
R> # Create some R objects.
R> df1 <- data.frame(x1 = 1:5, y1 = letters[1:5])
R> df2 <- data.frame(x2 = 5:1, y2 = letters[11:15])
R> iris_of <- ore.push(iris)
R>
R> # Create a database table and an Oracle R Enterprise proxy object for the table.
R> ore.drop("AIRQUALITY")
R> ore.create(airquality, table = "AIRQUALITY")
R>
R> # Save the objects to a datastore named ds1 and supply a description.
R> ore.save(AIRQUALITY, list = ls(), name = "ds1", description = "My private datastore")
R>
R> # Create some more objects.
R> x <- stats::runif(20) # x is an object of type numeric.
R> y <- list(a = 1, b = TRUE, c = "hoopsa")
R> z <- ore.push(x) # z is an object of type ore.numeric.
R>
R> # Create other datastores.
R> ore.save(x, y, name = "ds2", description = "x and y")
R> ore.save(df1, df2, name = "dfobj", description = "df objects")
R> ore.save(x, y, z, name = "another_ds", description = "For pattern matching")
R>
R> # List all of the datastore objects.
R> ore.datastore()
datastore.name object.count size creation.date description
1 another_ds 3 1284 2017-04-21 16:08:57 For pattern matching
2 dfobj 2 656 2017-04-21 16:08:38 df objects
3 ds1 4 3439 2017-04-21 16:03:55 My private datastore
4 ds2 2 314 2017-04-21 16:04:32 x and y
R> # List the specified datastore.
R> ore.datastore("ds1")
datastore.name object.count size creation.date description
1 ds1 4 3439 2017-04-21 16:03:55 My private datastore
R> # List the datastore objects with names that include "ds".
R> ore.datastore(pattern = "ds")
datastore.name object.count size creation.date description
1 another_ds 3 1284 2017-04-21 16:08:57 For pattern matching
2 ds1 4 3439 2017-04-21 16:03:55 My private datastore
3 ds2 2 314 2017-04-21 16:04:32 x and y
Example 2-21 Using the ore.datastoreSummary Function
This example demonstrates using the ore.datastoreSummary function. The example uses the datastores created in the previous example.
ore.datastoreSummary("ds1")
ore.datastoreSummary("ds2")
Listing for This Example
R> ore.datastoreSummary("ds1")
object.name class size length row.count col.count
1 AIRQUALITY ore.frame 1213 6 NA 6
2 df1 data.frame 328 2 5 2
3 df2 data.frame 328 2 5 2
4 iris_of ore.frame 1570 5 NA 5
R> ore.datastoreSummary("ds2")
object.name class size length row.count col.count
1 x numeric 182 20 NA NA
2 y list 132 3 NA NA
The ore.load function restores R objects saved in a datastore to the R global environment, .GlobalEnv. The function returns a character vector that contains the names of the restored objects.
You can load all of the saved objects or you can use the list argument to specify the objects to load. With the envir argument, you can specify an environment in which to load objects.
Example 2-22 Using the ore.load Function to Restore Objects from a Datastore
This example demonstrates using the ore.load function to restore objects from datastores that were created in Example 2-20. The example runs in the same R session as that example.
# List the R objects.
ls()
# List the datastores.
ore.datastore()
# Delete the x and z objects.
rm(x, z)
ls()
# Restore all of the objects in datastore ds2.
ore.load("ds2")
ls()
# After ending the R session and starting another session.
ls()
# The datastore objects persist between sessions.
ore.datastore()
# Restore some of the objects from datastore ds1.
ore.load("ds1", list = c("df1", "df2", "iris_of"))
ls()
Listing for Example 2-22
R> # List the R objects.
R> ls()
[1] "df1" "df2" "iris_of" "x" "y" "z"
R>
R> # List the datastores.
R> ore.datastore()
datastore.name object.count size creation.date description
1 another_ds 3 1243 2014-07-24 13:31:56 For pattern mattching
2 dfobj 2 656 2014-07-24 13:31:46 df objects
3 ds1 4 3162 2014-07-24 13:25:17 My datastore
4 ds2 2 1111 2014-07-24 13:27:26 only x
R>
R> # Delete the x and z objects.
R> rm(x, z)
R> ls()
[1] "df1" "df2" "iris_of" "y"
R>
R> # Restore all of the objects in datastore ds2.
R> ore.load("ds2")
[1] "x" "z"
R>
R> ls()
[1] "df1" "df2" "iris_of" "x" "y" "z"
R>
R> # After ending the R session and starting another session.
R> ls()
character(0)
R> # The datastore objects persist between sessions.
R> ore.datastore()
datastore.name object.count size creation.date description
1 another_ds 3 1243 2014-07-24 13:31:56 For pattern mattching
2 dfobj 2 656 2014-07-24 13:31:46 df objects
3 ds1 4 3162 2014-07-24 13:25:17 My datastore
4 ds2 2 1111 2014-07-24 13:27:26 only x
R> # Restore some of the objects from datastore ds1.
R> ore.load("ds1", list = c("df1", "df2", "iris_of"))
[1] "df1" "df2" "iris_of"
R> ls()
[1] "df1" "df2" "iris_of"
With the ore.delete function, you can delete objects from an Oracle R Enterprise datastore or you can delete the datastore itself. To delete a datastore, you specify the name of it. To delete one or more objects from the datastore, you specify the list argument. The ore.delete function returns the name of the deleted objects or datastore.
When you delete a datastore, Oracle R Enterprise discards all temporary database objects that were referenced by R objects in the deleted datastore. If you have saved an R object in more than one datastore, then Oracle R Enterprise discards a temporary database object only when no object in a datastore references the temporary database object.
Example 2-23 Using the ore.delete Function
This example demonstrates using ore.delete to delete an object from a datastore and then to delete the entire datastore. The example uses objects created in Example 2-18.
# Delete the df2 object from the ds1 datastore.
ore.delete("ds1", list = "df2")
# Delete the datastore named ds1.
ore.delete("ds1")
Listing for Example 2-23
R> # Delete the df2 object from the ds1 datastore.
R> ore.delete("ds1", list = "df2")[1] "df2"
R> # Delete the datastore named ds1.
R> ore.delete("ds1")
[1] "ds1"
Saving objects in a datastore makes it very easy to pass arguments to, and reference R objects with, embedded R execution functions. You can save objects that you create in one R session in a single datastore in the database. You can pass the name of this datastore to an embedded R function as an argument for loading within that function. You can use a datastore to easily pass one object or multiple objects.