1. SODA for C Developers Guide
  2. SODA Collection Configuration Using Custom Metadata

6 SODA Collection Configuration Using Custom Metadata

SODA collections are highly configurable. You can customize collection metadata, to obtain different behavior from that provided by default.

Note:

Although you can customize collection metadata to obtain different behavior from that provided by default, Oracle recommends against this unless you have a compelling reason. Customizing collection metadata requires familiarity with Oracle Database concepts, such as SQL data types. Because SODA collections are implemented on top of Oracle Database tables (or views), many collection configuration components are related to the underlying table configuration.

  • Getting the Metadata of an Existing Collection
    You can use OCI function OCIAttrGet() with attribute OCI_ATTR_SODA_DESCRIPTOR, to get all of the metadata of a collection at once, as a JSON document. You can also use OCIAttrGet() to get individual collection metadata attributes.
  • Creating a Collection That Has Custom Metadata
    To create a document collection that has custom metadata, you pass its metadata, as JSON data, to OCI function OCISodaCollCreateWithMetadata().

See Also:

6.1 Getting the Metadata of an Existing Collection

You can use OCI function OCIAttrGet() with attribute OCI_ATTR_SODA_DESCRIPTOR, to get all of the metadata of a collection at once, as a JSON document. You can also use OCIAttrGet() to get individual collection metadata attributes.

Table 6-1 Collection Handle Attributes (Collection Metadata)

Attribute Description

OCI_ATTR_SODA_CRTIME_COL_NAME

The name of the database column that stores the creation time stamp of the document.

OCI_ATTR_SODA_CTNT_CACHE

The SecureFiles LOB cache setting.

OCI_ATTR_SODA_CTNT_COL_NAME

The database column that stores the document content.

OCI_ATTR_SODA_CTNT_COMPRESS

The SecureFiles LOB compression setting.

OCI_ATTR_SODA_CTNT_ENCRYPT

The SecureFiles LOB encryption setting.

OCI_ATTR_SODA_CTNT_MAX_LEN

The maximum length, in bytes, of the database column that stores the document content. This attribute applies only to content of type VARCHAR2.

OCI_ATTR_SODA_CTNT_SQL_TYPE

The SQL data type of the database column that stores the document content.

OCI_ATTR_SODA_CTNT_VALIDATION

The syntax to which JavaScript Object Notation (JSON) content must conform — standard, strict, or lax.

OCI_ATTR_SODA_DESCRIPTOR

All of the metadata of the collection, in JSON format.

OCI_ATTR_SODA_KEY_ASSIGN_METHOD

The method used to assign keys to documents that are inserted into the collection.

OCI_ATTR_SODA_KEY_COL_NAME

The name of the database column that stores the document key.

OCI_ATTR_SODA_KEY_MAX_LEN

The maximum length, in bytes, of the database column that stores the document key. This attribute applies only to content of type VARCHAR2.

OCI_ATTR_SODA_KEY_SEQ_NAME

The name of the database sequence that generates keys for documents that are inserted into a collection if the key assignment method is SEQUENCE.

OCI_ATTR_SODA_KEY_SQL_TYPE

The SQL data type of the database column that stores the document key.

OCI_ATTR_SODA_MODTIME_COL_NAME

The name of the database column that stores the last-modified time stamp of the document.

OCI_ATTR_SODA_MODTIME_INDEX

The name of the index on the database column that stores the last-modified time stamp.

OCI_ATTR_SODA_READONLY

An indication of whether the collection is read-only.

OCI_ATTR_SODA_SCHEMA

The name of the Oracle Database schema (user) that owns the table or view to which the collection is mapped.

OCI_ATTR_SODA_TABLE_NAME

The name of the database table to which the collection is mapped.

OCI_ATTR_SODA_VERSION_COL_NAME

The name of the database column that stores the document version.

OCI_ATTR_SODA_VERSION_METHOD

The method used to compute version values for documents when they are inserted into a collection or replaced.

OCI_ATTR_SODA_VIEW_NAME

The name of the database view to which the collection is mapped.

See Also:

Example 6-1 Getting All of the Metadata of a Collection

This example shows the result of invoking function OCIAttrGet() for collection-handle attribute OCI_ATTR_SODA_DESCRIPTOR on the collection with the default configuration that was created using Example 3-2. This retrieves all of the collection metadata as JSON data. The default metadata for a collection is shown in Example 6-3. 

OraText *fetchedMetadata;
ub4      fetchedMetadataLen = 0;

rc = OCIAttrGet((dvoid *)collhp, 
                OCI_HTYPE_SODA_COLLECTION,
                (dvoid *)fetchedMetadata,
                &fetchedMetadataLen,
                OCI_ATTR_SODA_DESCRIPTOR, errhp);

if (rc == OCI_SUCCESS)
  printf ("Collection specification: %.*s\n", fetchedMetadataLen, fetchedMetadata);

Example 6-2 Getting Individual Collection Metadata Attributes

This example uses OCIAttrGet() to get individual collection metadata attributes. For each attribute, you pass the collection handle, the attribute, and the attribute type. 

// String collection metadata attribute
oratext *collAttr = NULL;

// Length of collection metadata attribute
// (relevant only for string attributes).
ub4      collAttrLen = 0;

ub1      ub1CollAttr = 0;
ub4      ub4CollAttr = 0;
boolean  boolCollAttr = FALSE;

// Get and print collection metadata components.
// (For brevity we omit checking the return values of the OCIAttrGet calls here.)

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_COLL_NAME,
           errhp);
printf("Collection name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_TABLE_NAME,
           errhp);
printf("Table name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_SCHEMA,
           errhp);
printf("Schema name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_KEY_COL_NAME,
           errhp);
printf("Key column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_KEY_SQL_TYPE,
           errhp);
if (ub1CollAttr == SQLT_CHR)
  printf ("Key column type: VARCHAR2\n");
else if (ub1CollAttr == SQLT_BIN)
  printf ("Key column type: RAW\n");
else if (ub1CollAttr == SQLT_NUM)
  printf ("Key column type: NUMBER\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub4CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_KEY_MAX_LEN,
           errhp);
printf ("Key column max length: %d\n", ub4CollAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_KEY_ASSIGN_METHOD,
           errhp);

if (ub1CollAttr == OCI_SODA_KEY_METHOD_UUID)
  printf ("Key assignment method: UUID\n");
else if (ub1CollAttr == OCI_SODA_KEY_METHOD_GUID)
  printf ("Key assignment method: GUID\n");
else if (ub1CollAttr == OCI_SODA_KEY_METHOD_SEQUENCE)
  printf ("Key assignment method: SEQUENCE\n");
else if (ub1CollAttr == OCI_SODA_KEY_METHOD_CLIENT)
  printf ("Key assignment method: CLIENT\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_CTNT_COL_NAME,
           errhp);
printf("Content column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen, 
           OCI_ATTR_SODA_CTNT_SQL_TYPE,
           errhp);
if (ub1CollAttr == SQLT_CHR)
  printf ("Content column type: VARCHAR2\n");
else if (ub1CollAttr == SQLT_BLOB)
  printf ("Content column type: BLOB\n");
else if (ub1CollAttr == SQLT_CLOB)
  printf ("Content column type: CLOB\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub4CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_CTNT_MAX_LEN,
           errhp);
printf ("Content column max length: %d\n", ub4CollAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION, 
           (dvoid *)(&ub1CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_CTNT_VALIDATION,
           errhp);
if (ub1CollAttr == OCI_SODA_JSON_VALIDATION_STRICT)
  printf ("Content column validation: STRICT\n");
else if (ub1CollAttr == OCI_SODA_JSON_VALIDATION_LAX)
  printf ("Content column validation: LAX\n");
else if (ub1CollAttr == OCI_SODA_JSON_VALIDATION_STD)
  printf ("Content column validation: STANDARD\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen, 
           OCI_ATTR_SODA_CTNT_COMPRESS,
           errhp);
if (ub1CollAttr == OCI_SODA_LOB_COMPRESS_NONE)
  printf ("Content column compress: NONE\n");
else if (ub1CollAttr == OCI_SODA_LOB_COMPRESS_HIGH)
  printf ("Content column compress: HIGH\n");
else if (ub1CollAttr == OCI_SODA_LOB_COMPRESS_MEDIUM)
  printf ("Content column compress:  MEDIUM\n");
else if (ub1CollAttr == OCI_SODA_LOB_COMPRESS_LOW)
  printf ("Content column compress: LOW\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_CTNT_ENCRYPT,
           errhp);
if (ub1CollAttr == OCI_SODA_LOB_ENCRYPT_NONE)
  printf ("Content column encrypt: NONE\n");
else if (ub1CollAttr == OCI_SODA_LOB_ENCRYPT_3DES168)
  printf ("Content column encrypt: 3DES168\n");
else if (ub1CollAttr == OCI_SODA_LOB_ENCRYPT_AES128)
  printf ("Content column encrypt: AES128\n");
else if (ub1CollAttr == OCI_SODA_LOB_ENCRYPT_AES192)
  printf ("Content column encrypt: AES192\n");
else if (ub1CollAttr == OCI_SODA_LOB_ENCRYPT_AES256)
  printf ("Content column encrypt: AES256\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&boolCollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_CTNT_CACHE,
           errhp);
if (boolCollAttr == TRUE)
  printf ("Content column cache: TRUE\n");
else
  printf ("Content column cache: FALSE\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_VERSION_COL_NAME,
           errhp);
printf("Version column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)(&ub1CollAttr),
           &collAttrLen,
           OCI_ATTR_SODA_VERSION_METHOD,
           errhp);
if (ub1CollAttr == OCI_SODA_VERSION_NONE)
  printf ("Version method: NONE\n");
else if (ub1CollAttr == OCI_SODA_VERSION_TIMESTAMP)
  printf ("Version method: TIMESTAMP\n");
else if (ub1CollAttr == OCI_SODA_VERSION_MD5)
  printf ("Version method: MD5\n");
else if (ub1CollAttr == OCI_SODA_VERSION_SHA256)
  printf ("Version method: SHA256\n");
else if (ub1CollAttr == OCI_SODA_VERSION_SEQUENTIAL)
  printf ("Version method: SEQUENTIAL\n");

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_MODTIME_COL_NAME,
           errhp);
printf("Last-modified column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_MODTIME_INDEX,
           errhp);
printf("Last-modified index name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_CRTIME_COL_NAME,
           errhp);
printf("Created-on column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)collAttr,
           &collAttrLen,
           OCI_ATTR_SODA_MTYPE_COL_NAME,
           errhp);
printf("Media type column name: %.*s\n", collAttrLen, collAttr);

OCIAttrGet((dvoid *)collhp,
           OCI_HTYPE_SODA_COLLECTION,
           (dvoid *)&boolCollAttr,
           &collAttrLen,
           OCI_ATTR_SODA_READONLY,
           errhp);

if (boolCollAttr == TRUE)
  printf("Collection is read-only");
else
  printf("Collection is not read-only");

Example 6-3 Default Collection Metadata

{
   "schemaName" : "mySchemaName",
   "tableName" : "myTableName",
   "keyColumn" :
   {
      "name" : "ID",
      "sqlType" : "VARCHAR2",
      "maxLength" : 255,
      "assignmentMethod" : "UUID"
   },
   "contentColumn" :
   {
      "name" : "JSON_DOCUMENT",
      "sqlType" : "BLOB",
      "compress" : "NONE",
      "cache" : true,
      "encrypt" : "NONE",
      "validation" : "STANDARD"
   },
   "versionColumn" :
   {
     "name" : "VERSION",
     "method" : "SHA256"
   },
   "lastModifiedColumn" :
   {
     "name" : "LAST_MODIFIED"
   },
   "creationTimeColumn" :
   {
      "name" : "CREATED_ON"
   },
   "readOnly" : false
}

Related Topics

Parent topic: SODA Collection Configuration Using Custom Metadata

6.2 Creating a Collection That Has Custom Metadata

To create a document collection that has custom metadata, you pass its metadata, as JSON data, to OCI function OCISodaCollCreateWithMetadata().

The optional metadata argument to OCI function OCISodaCollCreateWithMetadata() is a SODA collection specification. It is JSON data that specifies the metadata for the new collection.

If a collection with the same name already exists then it is simply opened and its handle is returned. If the metadata passed to OCISodaCollCreateWithMetadata() does not match that of the existing collection then the collection is not opened and an error is raised. To match, all metadata fields must have the same values.

See Also:

Example 6-4 Creating a Collection That Has Custom Metadata

This example creates a collection with custom metadata that specifies two metadata columns, named KEY (for document keys), and JSON (for document content type JSON). The key assignment method is CLIENT, and the content-column SQL data type is VARCHAR2. The example uses collection-handle attribute OCI_ATTR_SODA_DESCRIPTOR to get the complete metadata from the newly created collection. 

sword        rc = OCI_SUCCESS;
OCISodaColl *collhp = NULL;
OraText     *metadata ="{\"keyColumn\" : \
{\"name\" : \"KEY\", \"assignmentMethod\": \"CLIENT\" }, \
\"contentColumn\" : { \"name\" : \"JSON\", \"sqlType\": \"VARCHAR2\" } }";
OraText     *collName = "myCustomCollection";
OraText     *fetchedMetadata = NULL;
ub4          fetchedMetadataLen = 0;

rc = OCISodaCollCreateWithMetadata(svchp, 
                                   collName,
                                   (ub4) strlen(collName),
                                   metadata,
                                   (ub4) strlen(metadata),
                                   &collhp,
                                   errhp,
                                   OCI_DEFAULT));
if (rc != OCI_SUCCESS)
{
  printf(OCISodaCollCreateWithMetadata failed\n");
  goto finally;
}

rc = OCIAttrGet((dvoid *)collhp,
                OCI_HTYPE_SODA_COLLECTION,
                (dvoid *)fetchedMetadata,
                &fetchedMetadataLen,
                OCI_ATTR_SODA_DESCRIPTOR,
                errhp);

if (rc == OCI_SUCCESS)
{
  printf ("Collection specification: %.*s\n", fetchedMetadataLen, fetchedMetadata);
}

finally: ...

Here is the output, formatted for readability. The values of fields for keyColumn and contentColumn that are not specified in the collection specification are defaulted. The values of fields other than those provided in the collection specification (keyColumn and contentColumn) are also defaulted. The value of field tableName is defaulted from the collection name. The value of field schemaName is the database schema (user) that is current when the collection is created. 

Collection specification: {
  "schemaName" : "mySchemaName",
  "tableName" : "myCustomCollection",
  "keyColumn" :
  {
    "name" : "KEY",
    "sqlType" : "VARCHAR2",
    "maxLength" : 255,
    "assignmentMethod" : "CLIENT"
  },

"contentColumn" :
  {
    "name" : "JSON",
    "sqlType" : "VARCHAR2",
    "maxLength" : 4000,
    "validation" : "STANDARD"
  },
  "readOnly" : false
}

Related Topics

Parent topic: SODA Collection Configuration Using Custom Metadata