createDocument method

Future<Document> createDocument(Document request, String parent, String collectionId, { String? documentId, List<String>? mask_fieldPaths, List<String>? requestOptions_requestTags, String? $fields, })

Creates a new document.

request - The metadata request object.

Request parameters:

parent - Required. The parent resource. For example: projects/{project_id}/databases/{database_id}/documents or projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id} Value must have pattern ^projects/\[^/\]+/databases/\[^/\]+/documents/.*$.

collectionId - Required. The collection ID, relative to parent, to list. For example: chatrooms.

documentId - The client-assigned document ID to use for this document. Optional. If not specified, an ID will be assigned by the service.

mask_fieldPaths - The list of field paths in the mask. See Document.fields for a field path syntax reference.

requestOptions_requestTags - Optional. The request tags for the request. Request tags are user-provided strings used for usage monitoring, cost management, and observability. Callers can associate custom application context (such as component, microservice, feature name, or operation type) with database requests. These tags are collected and aggregated in usage and monitoring reports, allowing billable operations and usage metrics to be sliced and analyzed by tag. These tags only show up in monitoring and are visible in administrative operations (such as usage reports). They do not affect data storage, query semantics, or request execution. Cardinality and Best Practices: - Request tags are most effective when using a bounded set of distinct values (e.g., fewer than 100 distinct tags across an entire database). Using a large number of distinct tags may result in tags being omitted from top usage dashboards. - Use structured identifiers (for example: app=cart, env=prod, service=checkout) and avoid high-cardinality values such as UUIDs, request IDs, timestamps, user IDs, or document keys. - Do not include sensitive data or personally identifiable information (PII) in request tags, as they show up in administrative monitoring. The tags are processed as follows: - Leading and trailing whitespace is trimmed. - Empty tags (after trimming) are filtered out. - Truncated to a maximum of 510 characters. - Deduplicated within the same request. - Limited to a maximum of 50 tags per request (excess tags are silently discarded).

$fields - Selector specifying which fields to include in a partial response.

Completes with a Document.

Completes with a commons.ApiRequestError if the API endpoint returned an error.

If the used http.Client completes with an error when making a REST call, this method will complete with the same error.

Implementation

async.Future<Document> createDocument(
  Document request,
  core.String parent,
  core.String collectionId, {
  core.String? documentId,
  core.List<core.String>? mask_fieldPaths,
  core.List<core.String>? requestOptions_requestTags,
  core.String? $fields,
}) async {
  final body_ = convert.json.encode(request);
  final queryParams_ = <core.String, core.List<core.String>>{
    'documentId': ?documentId == null ? null : [documentId],
    'mask.fieldPaths': ?mask_fieldPaths,
    'requestOptions.requestTags': ?requestOptions_requestTags,
    'fields': ?$fields == null ? null : [$fields],
  };

  final url_ =
      'v1/' +
      core.Uri.encodeFull('$parent') +
      '/' +
      commons.escapeVariable('$collectionId');

  final response_ = await _requester.request(
    url_,
    'POST',
    body: body_,
    queryParams: queryParams_,
  );
  return Document.fromJson(response_ as core.Map<core.String, core.dynamic>);
}