com.mysql.cj.xdevapi

## Interface Collection

All Superinterfaces:
  DatabaseObject

    public interface Collection
    extends DatabaseObject

Representation of a document collection. This interface allows access to and manipulation of the collection through add/find/modify/remove statements.

### Nested Class Summary

### Nested classes/interfaces inherited from interface com.mysql.cj.xdevapi.DatabaseObject

`DatabaseObject.DbObjectStatus, DatabaseObject.DbObjectType`

### Method Summary

All Methods Instance Methods Abstract Methods
`AddStatement` `add(DbDoc... documents)` Add a sequence of documents.
`AddStatement` `add(DbDoc document)` Add a document in the form of a DbDoc.
`AddStatement` `add(Map<String,?> doc)` Add a document in the form of a Map.
`AddStatement` `add(String... jsonStrings)` Add one or more documents.
`Result` `addOrReplaceOne(String id, DbDoc doc)` Adds the document to the collection.
`Result` `addOrReplaceOne(String id, String jsonString)` Adds the document to the collection.
`long` `count()` Query the number of documents in this collection.
`Result` `createIndex(String indexName, DbDoc indexDefinition)` Create a new statement defining the creation of an index on this collection.
`Result` `createIndex(String indexName, String jsonIndexDefinition)` Create a new statement defining the creation of an index on this collection.
`void` `dropIndex(String indexName)` Create a new statement defining the removal of an index on this collection.
`FindStatement` `find()` Create a new find statement retrieving all documents in the collection.
`FindStatement` `find(String searchCondition)` Create a new find statement retrieving documents matching the given search condition.
`DbDoc` `getOne(String id)` Return the document with the given id.
`ModifyStatement` `modify(String searchCondition)` Create a new modify statement affecting documents matching the given search condition.
`DbDoc` `newDoc()` Create a new document.
`RemoveStatement` `remove(String searchCondition)` Create a new removal statement affecting documents matching the given search condition.
`Result` `removeOne(String id)` Removes the document with the given id.
`Result` `replaceOne(String id, DbDoc doc)` Takes in a document object that will replace the matching document.
`Result` `replaceOne(String id, String jsonString)` Takes in a document object that will replace the matching document.

### Methods inherited from interface com.mysql.cj.xdevapi.DatabaseObject

`existsInDatabase, getName, getSchema, getSession`

### Method Detail

#### add

    AddStatement add(Map<String,?> doc)

Add a document in the form of a Map.

Parameters:
  `doc` - map of key-value parameters representing the document fields
Returns:
  `AddStatement`

#### add

    AddStatement add(String... jsonStrings)

Add one or more documents.

Parameters:
  `jsonStrings` - one or more documents given as JSON strings
Returns:
  `AddStatement`

#### add

    AddStatement add(DbDoc document)

Add a document in the form of a DbDoc.

Parameters:
  `document` - `DbDoc`
Returns:
  `AddStatement`

#### add

    AddStatement add(DbDoc... documents)

Add a sequence of documents.

Parameters:
  `documents` - one or more documents given as `DbDoc`
Returns:
  `AddStatement`

#### find

    FindStatement find()

Create a new find statement retrieving all documents in the collection.

Returns:
  `FindStatement`

#### find

    FindStatement find(String searchCondition)

Create a new find statement retrieving documents matching the given search condition.

Parameters:
  `searchCondition` - condition expression
Returns:
  `FindStatement`

#### modify

    ModifyStatement modify(String searchCondition)

Create a new modify statement affecting documents matching the given search condition.

Parameters:
  `searchCondition` - condition expression
Returns:
  `ModifyStatement`

#### remove

    RemoveStatement remove(String searchCondition)

Create a new removal statement affecting documents matching the given search condition.

Parameters:
  `searchCondition` - condition expression
Returns:
  `RemoveStatement`

#### createIndex

    Result createIndex(String indexName,
                       DbDoc indexDefinition)

Create a new statement defining the creation of an index on this collection.

Example: collection.createIndex("myIndex", "{\"fields\": [{\"field\": \"$.myGeoJsonField\", \"type\": \"GEOJSON\", \"required\": true, \"options\": 2, \"srid\": 4326}], \"type\":\"SPATIAL\"}");

Parameters:
  `indexName` - index name
  `indexDefinition` - JSON document with the following fields:
  - fields: array of IndexField objects, each describing a single document member to be included in the index (see below)
  - type: string, (optional) the type of index. One of INDEX or SPATIAL (case insensitive). Default is INDEX and may be omitted.
  where single IndexField description consists of the following fields:
  - field: string, the full document path to the document member or field to be indexed
  - type: string, one of the supported SQL column types to map the field into (see below for a list). For numeric types, the optional UNSIGNED keyword may follow. For the TEXT type, the length to consider for indexing may be added. Type descriptions are case insensitive.
  - required: bool, (optional) true if the field is required to exist in the document. Defaults to false, except for GEOJSON where it defaults to true
  - options: int, (optional) special option flags for use when decoding GEOJSON data
  - srid: int, (optional) srid value for use when decoding GEOJSON data
Returns:
  `Result`

#### createIndex

    Result createIndex(String indexName,
                       String jsonIndexDefinition)

Create a new statement defining the creation of an index on this collection.

Example: collection.createIndex("myIndex", "{\"fields\": [{\"field\": \"$.myGeoJsonField\", \"type\": \"GEOJSON\", \"required\": true, \"options\": 2, \"srid\": 4326}], \"type\":\"SPATIAL\"}");

Parameters:
  `indexName` - index name
  `jsonIndexDefinition` - JSON document with the following fields:
  - fields: array of IndexField objects, each describing a single document member to be included in the index (see below)
  - type: string, (optional) the type of index. One of INDEX or SPATIAL. Default is INDEX and may be omitted.
  where single IndexField description consists of the following fields:
  - field: string, the full document path to the document member or field to be indexed
  - type: string, one of the supported SQL column types to map the field into (see below for a list). For numeric types, the optional UNSIGNED keyword may follow. For the TEXT type, the length to consider for indexing may be added.
  - required: bool, (optional) true if the field is required to exist in the document. Defaults to false, except for GEOJSON where it defaults to true
  - options: int, (optional) special option flags for use when decoding GEOJSON data
  - srid: int, (optional) srid value for use when decoding GEOJSON data
Returns:
  `Result`

#### dropIndex

    void dropIndex(String indexName)

Create a new statement defining the removal of an index on this collection.

Parameters:
  `indexName` - index name

#### count

    long count()

Query the number of documents in this collection.

Returns:
  The number of documents in this collection

#### newDoc

    DbDoc newDoc()

Create a new document.

Returns:
  `DbDoc`

#### replaceOne

    Result replaceOne(String id,
                      DbDoc doc)

Takes in a document object that will replace the matching document. If no matches are found, the function returns normally with no changes being made.

Parameters:
  `id` - the document id of the document to be replaced
  `doc` - the new document, which may contain expressions. If document contains an _id value, it is ignored.
Returns:
  Result object, which will indicate the number of affected documents (1 or 0, if none)

#### replaceOne

    Result replaceOne(String id,
                      String jsonString)

Takes in a document object that will replace the matching document. If no matches are found, the function returns normally with no changes being made.

Parameters:
  `id` - the document id of the document to be replaced
  `jsonString` - the new document, given as JSON string, which may contain expressions. If document contains an _id value, it is ignored.
Returns:
  Result object, which will indicate the number of affected documents (1 or 0, if none)

#### addOrReplaceOne

    Result addOrReplaceOne(String id,
                           DbDoc doc)

Adds the document to the collection. The following algorithm applies:

Parameters:
  `id` - the document id of the document to be replaced
  `doc` - the new document, which may contain expressions. If doc contains an _id value and it does not match the given id then the error will be thrown.
Returns:
  Result object, which will indicate the number of affected documents (0 - if none, 1 - if added, 2 - if replaced)

#### addOrReplaceOne

    Result addOrReplaceOne(String id,
                           String jsonString)

Adds the document to the collection. The following algorithm applies:

Parameters:
  `id` - the document id of the document to be replaced
  `jsonString` - the new document, given as JSON string, which may contain expressions. If doc contains an _id value and it does not match the given id then the error will be thrown.
Returns:
  Result object, which will indicate the number of affected documents (0 - if none, 1 - if added, 2 - if replaced)

#### getOne

    DbDoc getOne(String id)

Return the document with the given id.

Parameters:
  `id` - the document id of the document to be retrieved
Returns:
  the document, or NULL if no match found

#### removeOne

    Result removeOne(String id)

Removes the document with the given id.

Parameters:
  `id` - the document id of the document to be removed
Returns:
  Returns a Result object, which will indicate the number of removed documents (1 or 0, if none)

Copyright © 2016, 2025, Oracle and/or its affiliates.