Attributes

This section contains information about Cypress attributes.

General information

Each object in YTsaurus has a set of attributes associated with it. The set of attributes can be thought of as a key-value dictionary that is both readable and modifiable. Arbitrary non-empty strings can serve as attribute names. Random non-empty strings can be attribute names. Arbitrary YSON structures can be values.

There are two kinds of attributes: system attributes and user attributes.

The special path modifier /@ and the get, list, set, and remove commands are used to access object attributes. In addition to accessing an attribute as a whole, you can address a part of it if the attribute value is a composite type.

For more information about path modifiers, see YPath.

For the get and list commands, you can optionally specify a list of attributes that you need to return along with the objects found.

System attributes

Different types of objects have their own set of type-specific system attributes. For example, all objects have the id attribute, tables have the compression_codec and compressed_data_size attributes. For more information about the attributes inherent to all objects, see Objects.

System attributes are either modifiable (can be changed by the user), such as compression_codec, or unmodifiable, such as compressed_data_size. If you try to set an unmodifiable attribute, the system will return an error. Attempting to remove a system attribute will also cause an error.

Some attributes are inherited: compression_codec, erasure_codec, primary_medium, media, replication_factor, vital, tablet_cell_bundle, atomicity, commit_ordering, in_memory_mode, and optimize_for. Besides objects for which the semantics of these attributes is obvious (tables, files, etc.), these attributes can be set on composite nodes (i.e. on map and list nodes). Inherited attributes are nullable with respect to composite nodes. When no value for an inherited attribute is specified when creating a new object, that attribute gets the value of the closest ancestor node, or the default value if no ancestor up to the root has the attribute set.

System attributes can also be opaque (or computed). The value of an opaque attribute will be available only when explicitly requested with the get command, but will not be available when all attributes are requested. Specifically, when all attributes are requested, the value of an opaque attribute will be set to entity. Most often, attributes are declared as opaque when they have a large value (in terms of occupied memory) or take a long time to compute. In practical terms, if the value of an attribute is 100 KB or more, you should probably make it opaque. In this case, when all attributes are requested, it will not be returned, making it fast to read all attributes. To get the value of an opaque attribute, you must explicitly request it. An example of an opaque attribute will be a list of all table chunks (the chunk_ids attribute) or the total usage of resources by Cypress subtree (the recursive_resource_usage attribute).

Below is a list of attributes of YTsaurus system objects:

• Attributes of any object.
• Attributes of Cypress nodes.
• Attributes of static tables.
• Attributes of dynamic tables.
• Attributes of files.
• The compression_codec and erasure_codec attributes for tables and files.
• Attributes of transactions.
• Attributes of links.
• Attributes of accounts.
• Attributes of media.

User attributes

The user can set user-defined attributes.

How attributes are stored in the system

System attributes can be stored in various ways, depending on the object type. Some attributes are computed on the fly instead of being stored. All user attributes are stored as a single key-value dict. This dictionary is encoded as YSON, so accessing the value of a specific attribute requires YSON-decoding.

yt set //tmp/@my_attribute '{x=10; y=["hello"; "world"]}'
yt get //tmp/@my_attribute/x
10
yt get //tmp/@my_attribute/y/1
"world"

yt set //tmp/@my_attribute/y/@inner_attribute attr
yt get //tmp/@my_attribute/y/@inner_attribute
"attr"

Examples

# Getting all object attributes
yt get //tmp/@
{
  "creation_time" = "2013-12-06T19:00:48.256444Z";
  "locks" = [];
 ...
}

# Getting a specific object attribute
yt get //tmp/@type
"map_node"

# Setting a specific object attribute
yt set //tmp/@my_attribute "my_value"

# Removing an attribute
yt remove //tmp/@my_attribute

# creating a table
echo '{"a": 10, "b": "hello"}' | yt write //tmp/my_table --format json

# Getting the first table chunk
yt get //tmp/my_table/@chunk_ids/0
"3ab1-cd56f-3ec0064-c8998820"

# Removing a table
yt remove //tmp/my_table --force


# Requesting a list with attributes
yt list / --attribute type --format '<format=pretty>yson'
[
    <
        "type" = "map_node"
    > "home";
    <
        "type" = "map_node"
    > "kiwi";
   ....
]

Attributes on paths

A popular scenario for using attributes is annotating the path to tables and files when making requests. For more information, see Operation options and YPath.