Method mutate_in

acouchbase/collection.py:971–1029

Performs a mutate-in operation against a document. Allowing atomic modification of specific fields within a document. Also enables access to document extended-attributes (i.e. xattrs). Args: key (str): The key for the document look in. spec (Iterable[:class:`

(self,
                        key,  # type: str
                        spec,  # type: Iterable[Spec]
                        *opts,  # type: MutateInOptions
                        **kwargs,  # type: Any
                        )

            return await self._impl.lookup_in_all_replicas(req, transcoder, obs_handler)

    async def mutate_in(self,
                        key,  # type: str
                        spec,  # type: Iterable[Spec]
                        *opts,  # type: MutateInOptions
                        **kwargs,  # type: Any
                        ) -> MutateInResult:
        """Performs a mutate-in operation against a document. Allowing atomic modification of specific fields
        within a document. Also enables access to document extended-attributes (i.e. xattrs).

        Args:
            key (str): The key for the document look in.
            spec (Iterable[:class:`~couchbase.subdocument.Spec`]):  A list of specs describing the operations to
                perform on the document.
            opts (:class:`~couchbase.options.MutateInOptions`): Optional parameters for this operation.
            **kwargs (Dict[str, Any]): keyword arguments that can be used in place or to
                override provided :class:`~couchbase.options.MutateInOptions`

        Returns:
            Awaitable[:class:`~couchbase.result.MutateInResult`]: A future that contains an instance
            of :class:`~couchbase.result.MutateInResult` if successful.

        Raises:
            :class:`~couchbase.exceptions.DocumentNotFoundException`: If the key provided does not exist
                on the server.

        Examples:

            Simple mutate-in operation::

                import couchbase.subdocument as SD

                # ... other code ...

                bucket = cluster.bucket('travel-sample')
                collection = bucket.scope('inventory').collection('hotel')

                key = 'hotel_10025'
                res = await collection.mutate_in(key, (SD.replace("city", "New City"),))


            Simple mutate-in operation with options::

                from datetime import timedelta

                import couchbase.subdocument as SD
                from couchbase.options import MutateInOptions

                # ... other code ...

                key = 'hotel_10025'
                res = await collection.mutate_in(key,
                                            (SD.replace("city", "New City"),),
                                            MutateInOptions(timeout=timedelta(seconds=2)))

        """
        instruments = self._impl.observability_instruments
        async with ObservableRequestHandler.create(KeyValueOperationType.MutateIn, instruments) as obs_handler:
            req = self._impl.request_builder.build_mutate_in_request(key, spec, obs_handler, *opts, **kwargs)