table cf create

Creates a column family for a HPE Ezmeral Data Fabric binary or JSON table.

Permissions Required

To run this command, your user ID must have the following permissions:

NOTE
The mapr user is not treated as a superuser. HPE Ezmeral Data Fabric Database does not allow the mapr user to run this command unless that user is given the relevant permission or permissions with access-control expressions.

Syntax

CLI
/opt/mapr/bin/maprcli table cf create
  -path <Table path >
  -cfname <Column family name >
  [ -minversions <Min versions to keep> Default: 0 ]
  [ -maxversions <Max versions to keep> Default: 1 ]
  [ -ttl <Time to live> Enter 0 for forever, otherwise, enter time in seconds. Default: 0 ]
  [ -inmemory <In-memory> Default: false ]
  [ -compression <off|lzf|lz4|zlib> Default: table's compression setting is applied. ]
  [ -versionperm <Version Permissions> ]
  [ -compressionperm <Compression Permissions> ]
  [ -memoryperm <Memory Permissions> ]
  [ -readperm <Read Permissions> ]
  [ -writeperm <Write Permissions> ]
  [ -appendperm <Append Permissions> ]   
  [ -unmaskedreadperm <CF Unmasked Read Permission> ] 
  [ -jsonpath Json <Family Path - needed for JSON column family, like a.b.c> ]
  [ -securitypolicy <comma-delimited list of policies> ]
  [ -force <Force create non-default column family for json tabletype> Default: false ]
  [ -traverseperm <Traverse Permissions> ]
REST
curl -k -X POST 
  'http[s]://<host>:<port>/rest/table/cf/create?path=<path>&cfname=<name>&<parameters>'
  -u <username>:<password>
NOTE
The mapr user is not treated as a superuser. HPE Ezmeral Data Fabric Database does not allow the mapr user to run this command unless that user is given the relevant permission or permissions with access-control expressions.

Parameters

Parameter

Description
path

The path to the table.

  • For a path on the local cluster, start the path at the volume mount point. For example, for a table named test under volume1 which has a mount point at /volume1, specify the following path: /volume1/test
  • For a path on a remote cluster, you must also specify the cluster name in the path. For example, for a table named test under volume1 in the sanfrancisco cluster, specify the following path:/mapr/sanfrancisco/volume1/customer
cfname

The name of the column family to create.
minversions Applies to binary tables only: Minimum number of versions of column values to keep. The default is zero.
maxversions Applies to binary tables only: Maximum number of versions of column values to keep. The default is one.
ttl Time to live in seconds. When the age of the data in this column family exceeds the value of the ttl parameter, the data is purged. Setting the value of ttl to 0 is equivalent to allowing data to remain indefinitely. Default: 0
NOTE
If the value of -ttl for an existing column family in a JSON table is not 0, you cannot add another column family. You also cannot set the TTL for a JSON table if it has secondary indexes. See Setting TTL for Data.
inmemory

Boolean. Determines whether preference is given to values of this column family for storage with row keys. Because row keys are cached in memory in preference to row data, column-family data that is stored inline with the row keys is also cached in memory.

For all column families in a table together, up to 200 bytes of row data will be stored inline with each row key. Storing data inline with a row key might speed retrieval of the data from a column family because disk access can often be avoided. For each column family, up to 32 bytes can be stored inline with each row key even if its inmemory parameter is set to false, but preference will be given to column families where this parameter is set to true. A column family can have more than 32 bytes stored inline if its inmemory parameter is set to true.

If the total number of bytes for all column families together exceeds 200 for a row, then preference for inclusion within the inline storage for that row is given to column families that have the inmemory parameter set to true.

NOTE
All of the data for a column family are either stored in-line with the row key, or not stored at all. If the contents in a column family for a particular row are larger than the maximum number of bytes that are allowed to be stored for that column family, then data is not stored in-line for that column family.

The default value for the inmemory parameter is false.
compression The compression setting to use for the column family. Valid options are off, lzf, lz4, and zlib. The default setting is equal to the compression setting for the directory in which the table is located. To find out whether a directory is compressed and the type of compression, see Turning Compression On or Off on Directories Using the CLI.
versionperm Applies to binary tables only: Access Control Expression (ACE) for changing the value of the maxversions and minversions parameters. By default, permission is given to the value of defaultversionperm for the table.
compressionperm Applies to binary tables only: ACE for changing the value of the compression parameter. By default, permission is given to the value of defaultcompressionperm for the table.
memoryperm The ACE for changing the value of the inmemory parameter. Use single quotation marks around the ACE. By default, permission is given to the value of defaultmemoryperm for the table.
readperm

The ACE for column reads. Use single quotation marks around the ACE.

Reads require permission both at the column-family level and at the column level (for binary tables) or field level (for JSON tables). In JSON tables, this permission is inherited by fields within the column family.

By default, permission is given to the value of defaultreadperm for the table.
writeperm

The ACE for column writes (puts and deletes). Use single quotation marks around the ACE.

Writes require permission both at the column-family level and at the column level (for binary tables) or field level (for JSON tables). In JSON tables, this permission is inherited by fields within the column family.

By default, permission is given to the value of defaultwriteperm for the table.
appendperm

Applies to binary tables only: The ACE for column appends. Use single quotation marks around the ACE.

Column appends require permission both at the column-family level and at the column level. By default, permission is given to the value of defaultappendperm for the table.
jsonpath
Applies to JSON tables only: Specifies the path to the column family. The path is in dotted notation. For example, suppose the table contained JSON documents that were of this general structure: 
{
     "_id" : "ID",
     "a" :
          {
               "b" : 
                    {
                         "c" : "value",
                    },
               "e" : "value"
          }
}
You want to create a column family at the field d in the new path a.b.d because you plan to store image files in fields in that column family.
IMPORTANT
Ensure that the field at which you want to create the column family does not yet exist. Also ensure that there are no secondary indexes defined on the field. If the field does exist or is a field in an index, the data in the field could become inaccessible after you create the column family.
RESTRICTION
As of release 6.0, a column family cannot be deleted from a JSON table.
securitypolicy The security policy or policies that apply to the column family. One or more tags can be assigned to a column family at the same time. If a security policy is not specified during column-family creation, the column family inherits the table securitypolicy value as its own security policy at runtime. If a security policy is specified during column-family creation, the table security policy is enforced followed by the column-family security policy.
force Applies to JSON tables only: By default, every time you try to create a non-default column family in a JSON table, this command fails and returns a warning message that you should ensure there is no existing data at the specified path. Set this parameter to true if you want to override this warning mechanism and create a column family.
traverseperm
Applies to JSON tables only: The Access Control Expressions that specifies who has permission to pass over fields in JSON documents. For example, suppose that a JSON table contains documents of this general structure: 
{
     "_id" : "ID",
     "a" :
          {
               "b" : "value",
               "c" : "value"
          }
}
Suppose further that the user sjohnson has read permission on a.b, but not on a. For sjohnson to read a.b, the user needs the traverse permission on a. The user can then pass over field a to a.b.

This permission is inherited by fields within the column family. By default, this permission is given to the value of defaulttraverseperm for the JSON table.

unmaskedreadperm The unmaskedreadperm permission, when applied to a column of a JSON table with a dynamic data mask set, allows the user to read the data unmasked. Users without this permission have the masked data returned.

Default unmaskedreadperm permission on column family creation is set to the table-level defaultunmaskedreadperm permission set using the maprcli table create or the maprcli table edit command unless the unmaskedreadperm permission is specified when creating the column family. This setting will take effect for all new columns/fields within this CF) unless otherwise overridden by the maprcli table cf colperm command.

NOTE
If a field is specified as a column family JSON path name, that field cannot be defined as either an indexed or included field when creating an index. For example, suppose you have the following JSON table: 
{
    "_id" : "ID",
    "a" :
        {
            "b" : 
                {
                    "c" : "value",
                    "d" : "value"
                },
            "e" : "value"
        }
}
If you created a column family at field c in the JSON path a.b.c, when creating an index, field a.b.c cannot be defined as an indexed or included field. However, you can define, as either an indexed or included field, fields a, a.b, a.b.d.

Example

Creates a new column family mynewcf for table mytable, keeping four versions in memory:

CLI
/opt/mapr/bin/maprcli table cf create -path /volume1/mytable -cfname mynewcf \
  -maxversions 4 -inmemory true
REST
curl -X POST \
  'https://r1n1.sj.us:8443/rest/table/cf/create?path=%2Fvolume1%2Fmytable&cfname=mynewcf&maxversions=4&inmemory=true' \
  -u <username>:<password>