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.

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

    • cannot exceed 1500 characters (It) –

    • cannot be empty. (and) –

  • 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 (~*/[]) –

    • exceed 1500 bytes (cannot) –

    • cannot be empty. (and) –

  • 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.