Field Paths#
Utilities for managing / converting field paths to / from strings.
-
class
google.cloud.firestore_v1.field_path.
FieldPath
(*parts)[source]# Bases:
object
Field Path object for client use.
A field path is a sequence of element keys, separated by periods. Each element key can be either a simple identifier, or a full unicode string.
In the string representation of a field path, non-identifier elements must be quoted using backticks, with internal backticks and backslashes escaped with a backslash.
- Parameters
parts – (one or more strings) Indicating path of the key to be used.
-
static
document_id
()[source]# - A special FieldPath value to refer to the ID of a document. It can be used
in queries to sort or filter by the document ID.
Returns: A special sentinel value to refer to the ID of a document.
-
eq_or_parent
(other)[source]# Check whether
other
is an ancestor.- Returns
(bool) True IFF
other
is an ancestor or equal toself
, else False.
-
classmethod
from_api_repr
(api_repr)[source]# Factory: create a FieldPath from the string formatted per the API.
-
google.cloud.firestore_v1.field_path.
get_field_path
(field_names)# Create a field path from a list of nested field names.
A field path is a
.
-delimited concatenation of the field names. It is used to represent a nested field. For example, in the datathe field path
'aa.bb.cc'
represents that data stored indata['aa']['bb']['cc']
.
-
google.cloud.firestore_v1.field_path.
get_nested_value
(field_path, data)[source]# Get a (potentially nested) value from a dictionary.
If the data is nested, for example:
>>> data { 'top1': { 'middle2': { 'bottom3': 20, 'bottom4': 22, }, 'middle5': True, }, 'top6': b' foo', }
a field path can be used to access the nested data. For example:
>>> get_nested_value('top1', data) { 'middle2': { 'bottom3': 20, 'bottom4': 22, }, 'middle5': True, } >>> get_nested_value('top1.middle2', data) { 'bottom3': 20, 'bottom4': 22, } >>> get_nested_value('top1.middle2.bottom3', data) 20
See
field_path()
for more information on field paths.
-
google.cloud.firestore_v1.field_path.
parse_field_path
(api_repr)[source]# Parse a field path from into a list of nested field names.
See
field_path()
for more on field paths.- Parameters
api_repr (str) – The unique Firestore api representation which consists of either simple or UTF-8 field names. It cannot exceed 1500 bytes, and cannot be empty. Simple field names match
'^[_a-zA-Z][_a-zA-Z0-9]*$'
. All other field names are escaped by surrounding them with backticks.- Returns
The list of field names in the field path.
- Return type
List[str, ..]
-
google.cloud.firestore_v1.field_path.
render_field_path
(field_names)[source]# Create a field path from a list of nested field names.
A field path is a
.
-delimited concatenation of the field names. It is used to represent a nested field. For example, in the datathe field path
'aa.bb.cc'
represents that data stored indata['aa']['bb']['cc']
.
-
google.cloud.firestore_v1.field_path.
split_field_path
(path)[source]# Split a field path into valid elements (without dots).
- Parameters
path (str) – field path to be lexed.
- Returns
tokens
- Return type
List(str)
- Raises
ValueError – if the path does not match the elements-interspersed- with-dots pattern.