def set(self, document_data, merge=False) -> Any: """Replace the current document in the Firestore database. A write ``option`` can be specified to indicate preconditions of the "set" operation. If no ``option`` is specified and this document doesn't exist yet, this method will create it. Overwrites all content for the document with the fields in ``document_data``. This method performs almost the same functionality as :meth:`create`. The only difference is that this method doesn't make any requirements on the existence of the document (unless ``option`` is used), whereas as :meth:`create` will fail if the document already exists. Args: document_data (dict): Property names and values to use for replacing a document. merge (Optional[bool] or Optional[List<apispec>]): If True, apply merging instead of overwriting the state of the document. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the committed document. A write result contains an ``update_time`` field. """ batch = self._client.batch() batch.set(self, document_data, merge=merge) write_results = batch.commit() return _first_write_result(write_results)
async def create( self, document_data: dict, retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: """Create the current document in the Firestore database. Args: document_data (dict): Property names and values to use for creating a document. retry (google.api_core.retry.Retry): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (float): The timeout for this request. Defaults to a system-specified value. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the committed document. A write result contains an ``update_time`` field. Raises: :class:`~google.cloud.exceptions.Conflict`: If the document already exists. """ batch, kwargs = self._prep_create(document_data, retry, timeout) write_results = await batch.commit(**kwargs) return _first_write_result(write_results)
def test__first_write_result_more_than_one(): from google.cloud.firestore_v1.types import write from google.cloud.firestore_v1.base_document import _first_write_result result1 = write.WriteResult() result2 = write.WriteResult() write_results = [result1, result2] result = _first_write_result(write_results) assert result is result1
def test__first_write_result_success(): from google.protobuf import timestamp_pb2 from google.cloud.firestore_v1.types import write from google.cloud.firestore_v1.base_document import _first_write_result single_result = write.WriteResult(update_time=timestamp_pb2.Timestamp( seconds=1368767504, nanos=458000123)) write_results = [single_result] result = _first_write_result(write_results) assert result is single_result
def create(self, document_data) -> Any: """Create the current document in the Firestore database. Args: document_data (dict): Property names and values to use for creating a document. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the committed document. A write result contains an ``update_time`` field. Raises: :class:`~google.cloud.exceptions.Conflict`: If the document already exists. """ batch = self._client.batch() batch.create(self, document_data) write_results = batch.commit() return _first_write_result(write_results)
async def set( self, document_data: dict, merge: bool = False, retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: """Replace the current document in the Firestore database. A write ``option`` can be specified to indicate preconditions of the "set" operation. If no ``option`` is specified and this document doesn't exist yet, this method will create it. Overwrites all content for the document with the fields in ``document_data``. This method performs almost the same functionality as :meth:`create`. The only difference is that this method doesn't make any requirements on the existence of the document (unless ``option`` is used), whereas as :meth:`create` will fail if the document already exists. Args: document_data (dict): Property names and values to use for replacing a document. merge (Optional[bool] or Optional[List<apispec>]): If True, apply merging instead of overwriting the state of the document. retry (google.api_core.retry.Retry): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (float): The timeout for this request. Defaults to a system-specified value. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the committed document. A write result contains an ``update_time`` field. """ batch, kwargs = self._prep_set(document_data, merge, retry, timeout) write_results = await batch.commit(**kwargs) return _first_write_result(write_results)
async def update( self, field_updates: dict, option: _helpers.WriteOption = None, retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: """Update an existing document in the Firestore database. By default, this method verifies that the document exists on the server before making updates. A write ``option`` can be specified to override these preconditions. Each key in ``field_updates`` can either be a field name or a **field path** (For more information on **field paths**, see :meth:`~google.cloud.firestore_v1.client.Client.field_path`.) To illustrate this, consider a document with .. code-block:: python >>> snapshot = await document.get() >>> snapshot.to_dict() { 'foo': { 'bar': 'baz', }, 'other': True, } stored on the server. If the field name is used in the update: .. code-block:: python >>> field_updates = { ... 'foo': { ... 'quux': 800, ... }, ... } >>> await document.update(field_updates) then all of ``foo`` will be overwritten on the server and the new value will be .. code-block:: python >>> snapshot = await document.get() >>> snapshot.to_dict() { 'foo': { 'quux': 800, }, 'other': True, } On the other hand, if a ``.``-delimited **field path** is used in the update: .. code-block:: python >>> field_updates = { ... 'foo.quux': 800, ... } >>> await document.update(field_updates) then only ``foo.quux`` will be updated on the server and the field ``foo.bar`` will remain intact: .. code-block:: python >>> snapshot = await document.get() >>> snapshot.to_dict() { 'foo': { 'bar': 'baz', 'quux': 800, }, 'other': True, } .. warning:: A **field path** can only be used as a top-level key in ``field_updates``. To delete / remove a field from an existing document, use the :attr:`~google.cloud.firestore_v1.transforms.DELETE_FIELD` sentinel. So with the example above, sending .. code-block:: python >>> field_updates = { ... 'other': firestore.DELETE_FIELD, ... } >>> await document.update(field_updates) would update the value on the server to: .. code-block:: python >>> snapshot = await document.get() >>> snapshot.to_dict() { 'foo': { 'bar': 'baz', }, } To set a field to the current time on the server when the update is received, use the :attr:`~google.cloud.firestore_v1.transforms.SERVER_TIMESTAMP` sentinel. Sending .. code-block:: python >>> field_updates = { ... 'foo.now': firestore.SERVER_TIMESTAMP, ... } >>> await document.update(field_updates) would update the value on the server to: .. code-block:: python >>> snapshot = await document.get() >>> snapshot.to_dict() { 'foo': { 'bar': 'baz', 'now': datetime.datetime(2012, ...), }, 'other': True, } Args: field_updates (dict): Field names or paths to update and values to update with. option (Optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]): A write option to make assertions / preconditions on the server state of the document before applying changes. retry (google.api_core.retry.Retry): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (float): The timeout for this request. Defaults to a system-specified value. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the updated document. A write result contains an ``update_time`` field. Raises: ~google.cloud.exceptions.NotFound: If the document does not exist. """ batch, kwargs = self._prep_update(field_updates, option, retry, timeout) write_results = await batch.commit(**kwargs) return _first_write_result(write_results)
def set( self, document_data: dict, merge: bool = False, retry: retries.Retry = gapic_v1.method.DEFAULT, timeout: float = None, ) -> write.WriteResult: """Create / replace / merge a document in the Firestore database. - To "upsert" a document (create if it doesn't exist, replace completely if it does), leave the ``merge`` argument at its default: >>> document_data = {"a": 1, "b": {"c": "Two"}} >>> document.get().to_dict() is None # document exists False >>> document.set(document_data) >>> document.get().to_dict() == document_data # exists True - To "merge" ``document_data`` with an existing document (creating if the document does not exist), pass ``merge`` as True``: >>> document_data = {"a": 1, "b": {"c": "Two"}} >>> document.get().to_dict() == {"d": "Three", "b": {}} # exists >>> document.set(document_data, merge=True) >>> document.get().to_dict() == {"a": 1, "d": "Three", "b": {"c": "Two"}} True In this case, existing documents with top-level keys which are not present in ``document_data`` (``"d"``) will preserve the values of those keys. - To merge only specific fields of ``document_data`` with existing documents (creating if the document does not exist), pass ``merge`` as a list of field paths: >>> document_data = {"a": 1, "b": {"c": "Two"}} >>> document.get().to_dict() == {"b": {"c": "One", "d": "Four" }} # exists True >>> document.set(document_data, merge=["b.c"]) >>> document.get().to_dict() == {"b": {"c": "Two", "d": "Four" }} True For more information on field paths, see :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`. Args: document_data (dict): Property names and values to use for replacing a document. merge (Optional[bool] or Optional[List<fieldpath>]): If True, apply merging instead of overwriting the state of the document. retry (google.api_core.retry.Retry): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (float): The timeout for this request. Defaults to a system-specified value. Returns: :class:`~google.cloud.firestore_v1.types.WriteResult`: The write result corresponding to the committed document. A write result contains an ``update_time`` field. """ batch, kwargs = self._prep_set(document_data, merge, retry, timeout) write_results = batch.commit(**kwargs) return _first_write_result(write_results)
def _call_fut(write_results): from google.cloud.firestore_v1.base_document import _first_write_result return _first_write_result(write_results)
def test__first_write_result_failure_not_enough(): from google.cloud.firestore_v1.base_document import _first_write_result write_results = [] with pytest.raises(ValueError): _first_write_result(write_results)