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

Modifier and Type	Method and Description
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)