iCommands - Metadata

imeta

Usage: imeta [-vVhz] [command]
 -v verbose
 -V Very verbose
 -z Zonename  work with the specified Zone
 -h This help
Commands are:
 add -d|C|R|u Name AttName AttValue [AttUnits] (Add new AVU triple)
 adda -d|C|R|u Name AttName AttValue [AttUnits] (Add as administrator)
                                     (same as 'add' but bypasses ACLs)
 addw -d Name AttName AttValue [AttUnits] (Add new AVU triple
                                           using Wildcards in Name)
 rm  -d|C|R|u Name AttName AttValue [AttUnits] (Remove AVU)
 rmw -d|C|R|u Name AttName AttValue [AttUnits] (Remove AVU, use Wildcards)
 rmi -d|C|R|u Name MetadataID (Remove AVU by MetadataID)
 mod -d|C|R|u Name AttName AttValue [AttUnits] [n:Name] [v:Value] [u:Units]
      (modify AVU; new name (n:), value(v:), and/or units(u:)
 set -d|C|R|u Name AttName newValue [newUnits] (Assign a single value)
 ls  -[l]d|C|R|u Name [AttName] (List existing AVUs for item Name)
 lsw -[l]d|C|R|u Name [AttName] (List existing AVUs, use Wildcards)
 qu -d|C|R|u AttName Op AttVal [...] (Query objects with matching AVUs)
 cp -d|C|R|u -d|C|R|u Name1 Name2 (Copy AVUs from item Name1 to Name2)
 upper (Toggle between upper case mode for queries (qu))

Metadata attribute-value-units triples (AVUs) consist of an Attribute-Name, Attribute-Value, and an optional Attribute-Units. They can be added via the 'add' command (and in other ways), and then queried to find matching objects.

For each command, -d, -C, -R, or -u is used to specify which type of object to work with: dataobjs (iRODS files), collections, resources, or users.

Fields represented with upper case, such as Name, are entered values. For example, 'Name' is the name of a dataobject, collection, resource, or user.

For rmw and lsw, the % and _ wildcard characters (as defined for SQL) can be used for matching attribute values.

For addw, the % and _ wildcard characters (as defined for SQL) can be used for matching object names. This is currently implemented only for data-objects (-d).

A blank execute line invokes the interactive mode, where imeta prompts and executes commands until 'quit' or 'q' is entered. Like other unix utilities, a series of commands can be piped into it: 'cat file1 | imeta' (maintaining one connection for all commands).

Single or double quotes can be used to enter items with blanks.

Entered usernames are of the form username[#zone]. If #zone is not provided, the zone from your irods_environment.json is assumed.

The appropriate zone (local or remote) is determined from the path names or via -z Zonename (for 'qu' and when working with resources).

Try 'help command' for more help on a specific command. 'help qu' will explain additional options on the query.

add

 add -d|C|R|u Name AttName AttValue [AttUnits]  (Add new AVU triple)
Add an AVU to a dataobj (-d), collection(-C), resource(-R), 
or user(-u)
Example: add -d file1 distance 12 miles

Admins can also use the command 'adda' (add as admin) to add metadata to any collection or dataobj; syntax is the same as 'add'. Admins are also allowed to add user and resource metadata.

adda

 adda -d|C|R|u Name AttName AttValue [AttUnits]  (Add as administrator)
                                     (same as 'add' but bypasses ACLs)

Administrators (rodsadmin users) may use this command to add AVUs to any dataobj, collection, resource, or user. The syntax is the same as 'imeta add'.

addw

 addw -d Name AttName AttValue [AttUnits]  (Add new AVU triple)
Add an AVU to a set of data-objects using wildcards to match
the data-object names.

The character _ matches any single character and % matches any number of any characters.

Example: addw -d file% distance 12 miles would add the AVU to dataobjects in the current directory with names that start with 'file'.

Example2: addw -d /tempZone/home/rods/test/%/% distance 12 miles would add the AVU to all dataobjects in the 'test' collection or any subcollections under 'test'.

rm

 rm  -d|C|R|u Name AttName AttValue [AttUnits] (Remove AVU)
Remove an AVU from a dataobj (-d), collection(-C), resource(-R),
or user(-u)
Example: rm -d file1 distance 12 miles
An AttUnits value must be included if it was when the AVU was added.
Also see rmw for use of wildcard characters.

rmw

 rmw  -d|C|R|u Name AttName AttValue [AttUnits] (Remove AVU, use Wildcard)
Remove an AVU from a dataobj (-d), collection(-C), resource(-R), 
or user(-u)
An AttUnits value must be included if it was when the AVU was added.
rmw is very similar to rm but using SQL wildcard characters, _ and %.
The _ matches any single character and % matches any number of any
characters.  Examples:
  rmw -d file1 distance % %
 or 
  rmw -d file1 distance % m% 

Note that if the attributes contain the characters '%' or '_', the rmw command still do matching using them as wildcards, so you may need to use rm instead. Also see lsw.

rmi

 rmi -d|C|R|u Name MetadataID (Remove AVU by MetadataID)
Remove an AVU from a dataobj (-d), collection(-C), resource(-R),
or user(-u) by name and metadataID from the catalog.  Intended for
expert use.  There is no matching done to confirm correctness of
a request (but permissions are still checked).  Use with caution.

mod

 mod -d|C|R|u Name AttName AttValue [AttUnits] [n:Name] [v:Value] [u:Units]
      (modify AVU; new name (n:), value(v:), and/or units(u:)
Modify a defined AVU for the specified item (object)
Example: mod -d file1 distance 14 miles v:27

Only the AVU associated with this object is modified. Internally, the system removes the old AVU from the object and creates a new one (ensuring consistency), and performs a single 'commit' if all is valid.

set

 set -d|C|R|u Name AttName newValue [newUnits]  (assign a single value)
Set the newValue (and newUnit) of an AVU of a dataobj (-d), collection(-C),
     resource(-R) or user(-u).

'set' modifies an AVU if it exists, or creates one if it does not. If the AttName does not exist, or is used by multiple objects, the AVU for this object is added. If the AttName is used only by this one object, the AVU (row) is modified with the new values, reducing the database overhead (unused rows). Example: set -d file1 distance 12

ls

 ls -d|C|R|u Name [AttName] (List existing AVUs for item Name)
 ls -ld Name [AttName]        (List in long format)
List defined AVUs for the specified item
Example: ls -d file1
If the optional AttName is included, it is the attribute name
you wish to list and only those will be listed.
If the optional -l is used on dataObjects (-ld), the long format will
be displayed which includes the time the AVU was set.
Also see lsw.

lsw

 lsw -d|C|R|u Name [AttName] (List existing AVUs, use Wildcards)
List defined AVUs for the specified item
Example: lsw -d file1
If the optional AttName is included, it is the attribute name
you wish to list, doing so using wildcard matching.
For example: ls -d file1 attr%
If the optional -l is used on dataObjects (-ld), the long format will
be displayed which includes the time the AVU was set.
Also see rmw and ls.

qu

 qu -d|C|R|u AttName Op AttVal [...] (Query objects with matching AVUs)
Query across AVUs for the specified type of item
Example: qu -d distance '<=' 12

When querying dataObjects (-d) or collections (-C) additional conditions (AttName Op AttVal) may be given separated by 'and', for example: qu -d a = b and c '<' 10 Or a single 'or' can be given for the same AttName, for example qu -d r '<' 5 or '>' 7

You can also query in numeric mode (instead of as strings) by adding 'n' in front of the test condition, for example: qu -d r 'n<' 123 which causes it to cast the AVU column to numeric (decimal) in the SQL. In numeric mode, if any of the named AVU values are non-numeric, a SQL error will occur but this avoids problems when comparing numeric strings of different lengths.

Other examples: qu -d a like b% returns data-objects with attribute 'a' with a value that starts with 'b'. qu -d a like % returns data-objects with attribute 'a' defined (with any value).

cp

 cp -d|C|R|u -d|C|R|u Name1 Name2 (Copy AVUs from item Name1 to Name2)
Example: cp -d -C file1 dir1

upper

 upper (Toggle between upper case mode for queries (qu)
When enabled, the 'qu' queries will use the upper-case mode for the 'where'
clause, so you can do a case-insensitive query (using an upper case literal)
to compare against.  For example:
  upper
  qu -d A like B%
will return all dataobjects with an AVU named 'A' or 'a' with a value that
begins with 'b' or 'B'.