Field Paths

Utilities for managing / converting field paths to / from strings.

class google.cloud.firestore_v1.field_path.FieldPath(*parts)

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.

_add_(other)

Adds other field path to end of this field path.

• Parameters

  other (FieldPath, *[str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The field path to add to the end of this FieldPath.

static document_id()

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)

Check whether other is an ancestor.

• Returns

  (bool) True IFF other is an ancestor or equal to self, else False.

classmethod from_api_repr(api_repr: str)

Factory: create a FieldPath from the string formatted per the API.

• Parameters

  • api_repr (str) – a string path, with non-identifier elements quoted

  • characters (It cannot exceed 1500) –

  • empty. (and cannot be) –

• Returns

  (FieldPath) An instance parsed from api_repr.

• Raises

  ValueError if the parsing fails –

classmethod from_string(path_string: str)

Factory: create a FieldPath from a unicode string representation.

This method splits on the character . and disallows the characters ~*/[]. To create a FieldPath whose components have those characters, call the constructor.

• Parameters

  • path_string (str) – A unicode string which cannot contain

  • characters (~*/[]) –

  • bytes (cannot exceed 1500) –

  • empty. (and cannot be) –

• Returns

  (FieldPath) An instance parsed from path_string.

lineage()

Return field paths for all parents.

Returns: Set[FieldPath]

to_api_repr()

Render a quoted string representation of the FieldPath

• Returns

  (str) Quoted string representation of the path stored within this FieldPath.

google.cloud.firestore_v1.field_path.get_field_path(field_names: Iterable[str])

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 data

data = {
 'aa': {
 'bb': {
 'cc': 10,
 },
 },
}

the field path 'aa.bb.cc' represents that data stored in data['aa']['bb']['cc'].

• Parameters

  field_names – The list of field names.

• Returns

  The .-delimited field path.

• Return type

  str

google.cloud.firestore_v1.field_path.get_nested_value(field_path: str, data: dict)

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.

• Parameters

  • field_path (str) – A field path (.-delimited list of field names).

  • data (Dict[str , **Any]) – The (possibly nested) data.

• Returns

  (A copy of) the value stored for the field_path.

• Return type

  Any

• Raises

  KeyError – If the field_path does not match nested data.

google.cloud.firestore_v1.field_path.parse_field_path(api_repr: str)

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: Iterable[str])

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 data

data = {
 'aa': {
 'bb': {
 'cc': 10,
 },
 },
}

the field path 'aa.bb.cc' represents that data stored in data['aa']['bb']['cc'].

• Parameters

  field_names – The list of field names.

• Returns

  The .-delimited field path.

• Return type

  str

google.cloud.firestore_v1.field_path.split_field_path(path: str)

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.