@@ -65,7 +65,14 @@ def create(
6565 retry : retries .Retry = gapic_v1 .method .DEFAULT ,
6666 timeout : float = None ,
6767 ) -> write .WriteResult :
68- """Create the current document in the Firestore database.
68+ """Create a document in the Firestore database.
69+
70+ >>> document_data = {"a": 1, "b": {"c": "Two"}}
71+ >>> document.get().to_dict() is None # does not exist
72+ True
73+ >>> document.create(document_data)
74+ >>> document.get().to_dict() == document_data # exists
75+ True
6976
7077 Args:
7178 document_data (dict): Property names and values to use for
@@ -95,23 +102,51 @@ def set(
95102 retry : retries .Retry = gapic_v1 .method .DEFAULT ,
96103 timeout : float = None ,
97104 ) -> write .WriteResult :
98- """Replace the current document in the Firestore database.
105+ """Create / replace / merge a document in the Firestore database.
106+
107+ - To "upsert" a document (create if it doesn't exist, replace completely
108+ if it does), leave the ``merge`` argument at its default:
109+
110+ >>> document_data = {"a": 1, "b": {"c": "Two"}}
111+ >>> document.get().to_dict() is None # document exists
112+ False
113+ >>> document.set(document_data)
114+ >>> document.get().to_dict() == document_data # exists
115+ True
116+
117+ - To "merge" ``document_data`` with an existing document (creating if
118+ the document does not exist), pass ``merge`` as True``:
119+
120+ >>> document_data = {"a": 1, "b": {"c": "Two"}}
121+ >>> document.get().to_dict() == {"d": "Three", "b": {}} # exists
122+ >>> document.set(document_data, merge=True)
123+ >>> document.get().to_dict() == {"a": 1, "d": "Three", "b": {"c": "Two"}}
124+ True
125+
126+ In this case, existing documents with top-level keys which are
127+ not present in ``document_data`` (``"d"``) will preserve the values
128+ of those keys.
129+
130+
131+ - To merge only specific fields of ``document_data`` with existing
132+ documents (creating if the document does not exist), pass ``merge``
133+ as a list of field paths:
134+
99135
100- A write ``option`` can be specified to indicate preconditions of
101- the "set" operation. If no ``option`` is specified and this document
102- doesn't exist yet, this method will create it.
136+ >>> document_data = {"a": 1, "b": {"c": "Two"}}
137+ >>> document.get().to_dict() == {"b": {"c": "One", "d": "Four" }} # exists
138+ True
139+ >>> document.set(document_data, merge=["b.c"])
140+ >>> document.get().to_dict() == {"b": {"c": "Two", "d": "Four" }}
141+ True
103142
104- Overwrites all content for the document with the fields in
105- ``document_data``. This method performs almost the same functionality
106- as :meth:`create`. The only difference is that this method doesn't
107- make any requirements on the existence of the document (unless
108- ``option`` is used), whereas as :meth:`create` will fail if the
109- document already exists.
143+ For more information on field paths, see
144+ :meth:`~google.cloud.firestore_v1.base_client.BaseClient.field_path`.
110145
111146 Args:
112147 document_data (dict): Property names and values to use for
113148 replacing a document.
114- merge (Optional[bool] or Optional[List<apispec >]):
149+ merge (Optional[bool] or Optional[List<fieldpath >]):
115150 If True, apply merging instead of overwriting the state
116151 of the document.
117152 retry (google.api_core.retry.Retry): Designation of what errors, if any,
@@ -142,9 +177,9 @@ def update(
142177 override these preconditions.
143178
144179 Each key in ``field_updates`` can either be a field name or a
145- **field path** (For more information on ** field paths** , see
146- :meth:`~google.cloud.firestore_v1.client.Client .field_path`.) To
147- illustrate this, consider a document with
180+ **field path** (For more information on field paths, see
181+ :meth:`~google.cloud.firestore_v1.base_client.BaseClient .field_path`.)
182+ To illustrate this, consider a document with
148183
149184 .. code-block:: python
150185
0 commit comments