cosmos/orm
Table of Contents
cosmos/orm/module/v1alpha1/module.proto
TopModule
Module defines the ORM module which adds providers to the app container for
ORM ModuleDB's and in the future will automatically register query
services for modules that use the ORM.
cosmos/orm/query/v1alpha1/query.proto
TopGetRequest
GetRequest is the Query/Get request type.
| Field | Type | Label | Description |
| message_name | string | message_name is the fully-qualified message name of the ORM table being queried. |
|
| index | string | index is the index fields expression used in orm definitions. If it is empty, the table's primary key is assumed. If it is non-empty, it must refer to an unique index. |
|
| values | IndexValue | repeated | values are the values of the fields corresponding to the requested index. There must be as many values provided as there are fields in the index and these values must correspond to the index field types. |
GetResponse
GetResponse is the Query/Get response type.
| Field | Type | Label | Description |
| result | google.protobuf.Any | result is the result of the get query. If no value is found, the gRPC status code NOT_FOUND will be returned. |
IndexValue
IndexValue represents the value of a field in an ORM index expression.
| Field | Type | Label | Description |
| uint | uint64 | uint specifies a value for an uint32, fixed32, uint64, or fixed64 index field. |
|
| int | int64 | int64 specifies a value for an int32, sfixed32, int64, or sfixed64 index field. |
|
| str | string | str specifies a value for a string index field. |
|
| bytes | bytes | bytes specifies a value for a bytes index field. |
|
| enum | string | enum specifies a value for an enum index field. |
|
| bool | bool | bool specifies a value for a bool index field. |
|
| timestamp | google.protobuf.Timestamp | timestamp specifies a value for a timestamp index field. |
|
| duration | google.protobuf.Duration | duration specifies a value for a duration index field. |
ListRequest
ListRequest is the Query/List request type.
| Field | Type | Label | Description |
| message_name | string | message_name is the fully-qualified message name of the ORM table being queried. |
|
| index | string | index is the index fields expression used in orm definitions. If it is empty, the table's primary key is assumed. |
|
| prefix | ListRequest.Prefix | prefix defines a prefix query. |
|
| range | ListRequest.Range | range defines a range query. |
|
| pagination | cosmos.base.query.v1beta1.PageRequest | pagination is the pagination request. |
ListRequest.Prefix
Prefix specifies the arguments to a prefix query.
| Field | Type | Label | Description |
| values | IndexValue | repeated | values specifies the index values for the prefix query. It is valid to special a partial prefix with fewer values than the number of fields in the index. |
ListRequest.Range
Range specifies the arguments to a range query.
| Field | Type | Label | Description |
| start | IndexValue | repeated | start specifies the starting index values for the range query. It is valid to provide fewer values than the number of fields in the index. |
| end | IndexValue | repeated | end specifies the inclusive ending index values for the range query. It is valid to provide fewer values than the number of fields in the index. |
ListResponse
ListResponse is the Query/List response type.
| Field | Type | Label | Description |
| results | google.protobuf.Any | repeated | results are the results of the query. |
| pagination | cosmos.base.query.v1beta1.PageResponse | pagination is the pagination response. |
Query
Query is a generic gRPC service for querying ORM data.
| Method Name | Request Type | Response Type | Description |
| Get | GetRequest | GetResponse | Get queries an ORM table against an unique index. |
| List | ListRequest | ListResponse | List queries an ORM table against an index. |
cosmos/orm/v1alpha1/schema.proto
TopModuleSchemaDescriptor
ModuleSchemaDescriptor describe's a module's ORM schema.
| Field | Type | Label | Description |
| schema_file | ModuleSchemaDescriptor.FileEntry | repeated |
|
| prefix | bytes | prefix is an optional prefix that precedes all keys in this module's store. |
ModuleSchemaDescriptor.FileEntry
FileEntry describes an ORM file used in a module.
| Field | Type | Label | Description |
| id | uint32 | id is a prefix that will be varint encoded and prepended to all the table keys specified in the file's tables. |
|
| proto_file_name | string | proto_file_name is the name of a file .proto in that contains table definitions. The .proto file must be in a package that the module has referenced using cosmos.app.v1.ModuleDescriptor.use_package. |
|
| storage_type | StorageType | storage_type optionally indicates the type of storage this file's tables should used. If it is left unspecified, the default KV-storage of the app will be used. |
StorageType
StorageType
| Name | Number | Description |
| STORAGE_TYPE_DEFAULT_UNSPECIFIED | 0 | STORAGE_TYPE_DEFAULT_UNSPECIFIED indicates the persistent storage where all data is stored in the regular Merkle-tree backed KV-store. |
| STORAGE_TYPE_MEMORY | 1 | STORAGE_TYPE_MEMORY indicates in-memory storage that will be reloaded every time an app restarts. Tables with this type of storage will by default be ignored when importing and exporting a module's state from JSON. |
| STORAGE_TYPE_TRANSIENT | 2 | STORAGE_TYPE_TRANSIENT indicates transient storage that is reset at the end of every block. Tables with this type of storage will by default be ignored when importing and exporting a module's state from JSON. |
File-level Extensions
| Extension | Type | Base | Number | Description |
| module_schema | ModuleSchemaDescriptor | .google.protobuf.MessageOptions | 104503792 | module_schema is used to define the ORM schema for an app module. All module config messages that use module_schema must also declare themselves as app module config messages using the cosmos.app.v1.is_module option. |
cosmos/orm/v1/orm.proto
TopPrimaryKeyDescriptor
PrimaryKeyDescriptor describes a table primary key.
| Field | Type | Label | Description |
| fields | string | fields is a comma-separated list of fields in the primary key. Spaces are not allowed. Supported field types, their encodings, and any applicable constraints are described below. - uint32 are encoded as 2,3,4 or 5 bytes using a compact encoding that is suitable for sorted iteration (not varint encoding). This type is well-suited for small integers. - uint64 are encoded as 2,4,6 or 9 bytes using a compact encoding that is suitable for sorted iteration (not varint encoding). This type is well-suited for small integers such as auto-incrementing sequences. - fixed32, fixed64 are encoded as big-endian fixed width bytes and support sorted iteration. These types are well-suited for encoding fixed with decimals as integers. - string's are encoded as raw bytes in terminal key segments and null-terminated in non-terminal segments. Null characters are thus forbidden in strings. string fields support sorted iteration. - bytes are encoded as raw bytes in terminal segments and length-prefixed with a 32-bit unsigned varint in non-terminal segments. - int32, sint32, int64, sint64, sfixed32, sfixed64 are encoded as fixed width bytes with an encoding that enables sorted iteration. - google.protobuf.Timestamp is encoded such that values with only seconds occupy 6 bytes, values including nanos occupy 9 bytes, and nil values occupy 1 byte. When iterating, nil values will always be ordered last. Seconds and nanos values must conform to the officially specified ranges of 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z and 0 to 999,999,999 respectively. - google.protobuf.Duration is encoded as 12 bytes using an encoding that enables sorted iteration. - enum fields are encoded using varint encoding and do not support sorted iteration. - bool fields are encoded as a single byte 0 or 1. All other fields types are unsupported in keys including repeated and oneof fields. Primary keys are prefixed by the varint encoded table id and the byte 0x0 plus any additional prefix specified by the schema. |
|
| auto_increment | bool | auto_increment specifies that the primary key is generated by an auto-incrementing integer. If this is set to true fields must only contain one field of that is of type uint64. |
SecondaryIndexDescriptor
PrimaryKeyDescriptor describes a table secondary index.
| Field | Type | Label | Description |
| fields | string | fields is a comma-separated list of fields in the index. The supported field types are the same as those for PrimaryKeyDescriptor.fields. Index keys are prefixed by the varint encoded table id and the varint encoded index id plus any additional prefix specified by the schema. In addition the field segments, non-unique index keys are suffixed with any additional primary key fields not present in the index fields so that the primary key can be reconstructed. Unique indexes instead of being suffixed store the remaining primary key fields in the value.. |
|
| id | uint32 | id is a non-zero integer ID that must be unique within the indexes for this table and less than 32768. It may be deprecated in the future when this can be auto-generated. |
|
| unique | bool | unique specifies that this an unique index. |
SingletonDescriptor
TableDescriptor describes an ORM singleton table which has at most one instance.
| Field | Type | Label | Description |
| id | uint32 | id is a non-zero integer ID that must be unique within the tables and singletons in this file. It may be deprecated in the future when this can be auto-generated. |
TableDescriptor
TableDescriptor describes an ORM table.
| Field | Type | Label | Description |
| primary_key | PrimaryKeyDescriptor | primary_key defines the primary key for the table. |
|
| index | SecondaryIndexDescriptor | repeated | index defines one or more secondary indexes. |
| id | uint32 | id is a non-zero integer ID that must be unique within the tables and singletons in this file. It may be deprecated in the future when this can be auto-generated. |
File-level Extensions
| Extension | Type | Base | Number | Description |
| singleton | SingletonDescriptor | .google.protobuf.MessageOptions | 104503791 | singleton specifies that this message will be used as an ORM singleton. It cannot be used together with the table option. |
| table | TableDescriptor | .google.protobuf.MessageOptions | 104503790 | table specifies that this message will be used as an ORM table. It cannot be used together with the singleton option. |
Scalar Value Types
| .proto Type | Notes | Python Type |
| double | float | |
| float | float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int/long |
| uint32 | Uses variable-length encoding. | int/long |
| uint64 | Uses variable-length encoding. | int/long |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int/long |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | int |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | int/long |
| sfixed32 | Always four bytes. | int |
| sfixed64 | Always eight bytes. | int/long |
| bool | boolean | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | str/unicode |
| bytes | May contain any arbitrary sequence of bytes. | str |