<commit_before># ERMrest Data Operations

The [ERMrest](http://github.com/informatics-isi-edu/ermrest) data operations manipulate tabular data structured according to the existing entity-relationship model already configured as schemata resources in the catalog.

In the following examples, we illustrate the use of specific data formats. However, content negotiation allows any of the supported tabular data formats to be used in any request or response involving tabular data.

## Entity Creation

The POST operation is used to create new entity records in a table, using an `entity` resource data name of the form:

- _service_ `/catalog/` _cid_ `/entity/` _table name_
- _service_ `/catalog/` _cid_ `/entity/` _schema name_ `:` _table name_

In this operation, complex entity paths with filter and linked entity elements are not allowed.  The request input includes all columns of the table, thus supplying full entity records of data:

    POST /ermrest/catalog/42/entity/schema_name:table_name HTTP/1.1
    Host: www.example.com
    Content-Type: text/csv
    Accept: text/csv

    column1,column2
    1,foo
    2,foo
    3,bar
    4,baz

The input data MUST observe the table definition including column names and types, uniqueness constraints for key columns, and validity of any foreign key references. It is an error for any existing key in the stored table to match any key in the input data, as this would denote the creation of multiple rows with the same keys.

For convenience, the ERMrest system columns (`RID`, `RCT`, `RMT`, `RCB`, `RMB`) are implicitly supplied with default values during entity creation.

On success, the response is:

    HTTP/1.1 200 OK
    Content-Type: text/csv

    column1,column2
    1,foo
    2,foo
    3,bar
    4,baz

Typical error response codes include:
- 400 Bad Request
- 409 Conflict
- 403 Forbidden
- 401 Unauthorized

### Entity Creation with Defaults

The POST operation is also used to create new entity records in a table where some values are assigned default values, using an entity resource data name of the form:

- _service_ `/catalog/` _cid_ `/entity/` _table name_ `?defaults=` _column name_
- _service_ `/catalog/` _cid_ `/entity/` _schema name_ `:` _table name_ `?defaults=` _column name_ `,` ...
- _service_ `/catalog/` _cid_ `/entity/` _table name_ `?defaults=` _column name_ `&nondefaults=` _column name_ `,` ...

In this operation, complex entity paths with filter and linked entity elements are not allowed.  The request input includes all columns of the table, thus supplying full entity records of data:

    POST /ermrest/catalog/42/entity/schema_name:table_name?defaults=column1 HTTP/1.1
    Host: www.example.com
    Content-Type: text/csv
    Accept: text/csv

    column1,column2
    1,foo
    1,bar
    1,baz
    1,bof

The input data MUST observe the table definition including column names and types, uniqueness constraints for key columns, and validity of any foreign key references. If multiple columns are to be set to defaults, they are provided as a comma-separated list of column names on the right-hand-side of the `defaults=...` query parameter binding.

All columns should still be present in the input. However, the values for the column (or columns) named in the `defaults` query parameter will be ignored and server-assigned values generated instead. It is an error for any existing key in the stored table to match any key in the input data, as this would denote the creation of multiple rows with the same keys.

For convenience, columns lacking `enumerate` privilege and the ERMrest system columns (`RID`, `RCT`, `RMT`, `RCB`, `RMB`) are implicitly supplied with default values during entity creation, even if they are not listed in the `defaults` query parameter. The optional `nondefaults` query parameter can be used to suppress this implicit behavior, e.g. to allow a client to import or relocate table content from another catalog while preserving its originally assigned `RID`, `RCT`, and `RCB` values. NOTE: the server will also allow a privileged client to send values for `RMT` and `RMB`, but the current implementation of system columns will always override with a system-determined value reflecting the actual data mutation request transaction metadata.

On success, the response is:

    HTTP/1.1 200 OK
    Content-Type: text/csv

    column1,column2
    4,foo
    5,bar
    6,baz
    7,bof

In this example, a presumed `serial4` type used for `column1` would lead to a sequence of serial numbers being issued for the default column.

Typical error response codes include:
- 400 Bad Request
- 409 Conflict
- 403 Forbidden
- 401 Unauthorized

## Entity Update

The PUT operation is used to update entity records in a table, using an `entity` resource data name of the form:<commit_msg>revise misleading doc change for nondefaults param and RMB, RMT columns [ci skip]<commit_after># ERMrest Data Operations

The [ERMrest](http://github.com/informatics-isi-edu/ermrest) data operations manipulate tabular data structured according to the existing entity-relationship model already configured as schemata resources in the catalog.

In the following examples, we illustrate the use of specific data formats. However, content negotiation allows any of the supported tabular data formats to be used in any request or response involving tabular data.

## Entity Creation

The POST operation is used to create new entity records in a table, using an `entity` resource data name of the form:

- _service_ `/catalog/` _cid_ `/entity/` _table name_
- _service_ `/catalog/` _cid_ `/entity/` _schema name_ `:` _table name_

In this operation, complex entity paths with filter and linked entity elements are not allowed.  The request input includes all columns of the table, thus supplying full entity records of data:

    POST /ermrest/catalog/42/entity/schema_name:table_name HTTP/1.1
    Host: www.example.com
    Content-Type: text/csv
    Accept: text/csv

    column1,column2
    1,foo
    2,foo
    3,bar
    4,baz

The input data MUST observe the table definition including column names and types, uniqueness constraints for key columns, and validity of any foreign key references. It is an error for any existing key in the stored table to match any key in the input data, as this would denote the creation of multiple rows with the same keys.

For convenience, the ERMrest system columns (`RID`, `RCT`, `RMT`, `RCB`, `RMB`) are implicitly supplied with default values during entity creation.

On success, the response is:

    HTTP/1.1 200 OK
    Content-Type: text/csv

    column1,column2
    1,foo
    2,foo
    3,bar
    4,baz

Typical error response codes include:
- 400 Bad Request
- 409 Conflict
- 403 Forbidden
- 401 Unauthorized

### Entity Creation with Defaults

The POST operation is also used to create new entity records in a table where some values are assigned default values, using an entity resource data name of the form:

- _service_ `/catalog/` _cid_ `/entity/` _table name_ `?defaults=` _column name_
- _service_ `/catalog/` _cid_ `/entity/` _schema name_ `:` _table name_ `?defaults=` _column name_ `,` ...
- _service_ `/catalog/` _cid_ `/entity/` _table name_ `?defaults=` _column name_ `&nondefaults=` _column name_ `,` ...

In this operation, complex entity paths with filter and linked entity elements are not allowed.  The request input includes all columns of the table, thus supplying full entity records of data:

    POST /ermrest/catalog/42/entity/schema_name:table_name?defaults=column1 HTTP/1.1
    Host: www.example.com
    Content-Type: text/csv
    Accept: text/csv

    column1,column2
    1,foo
    1,bar
    1,baz
    1,bof

The input data MUST observe the table definition including column names and types, uniqueness constraints for key columns, and validity of any foreign key references. If multiple columns are to be set to defaults, they are provided as a comma-separated list of column names on the right-hand-side of the `defaults=...` query parameter binding.

All columns should still be present in the input. However, the values for the column (or columns) named in the `defaults` query parameter will be ignored and server-assigned values generated instead. It is an error for any existing key in the stored table to match any key in the input data, as this would denote the creation of multiple rows with the same keys.

For convenience, columns lacking `enumerate` privilege and the ERMrest system columns (`RID`, `RCT`, `RMT`, `RCB`, `RMB`) are implicitly supplied with default values during entity creation, even if they are not listed in the `defaults` query parameter. The optional `nondefaults` query parameter can be used to suppress this implicit behavior, e.g. to allow a client to import or relocate table content from another catalog while preserving its originally assigned `RID`, `RCT`, and `RCB` values. NOTE: the system will refuse attempts by clients to write values for `RMT` and `RMB` regardless of circumstance.

On success, the response is:

    HTTP/1.1 200 OK
    Content-Type: text/csv

    column1,column2
    4,foo
    5,bar
    6,baz
    7,bof

In this example, a presumed `serial4` type used for `column1` would lead to a sequence of serial numbers being issued for the default column.

Typical error response codes include:
- 400 Bad Request
- 409 Conflict
- 403 Forbidden
- 401 Unauthorized

## Entity Update

The PUT operation is used to update entity records in a table, using an `entity` resource data name of the form:
{'fraction_non_alphanumeric': 0.06362393521926596, 'fraction_numerical': 0.014512567041749922, 'mean_word_length': 4.015822784810126, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6782377', 'n_tokens_mistral': 2626, 'n_tokens_neox': 2474, 'n_words': 1321}