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)

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)

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)

Create a field pathfrom a list of nested field names.

A field pathis a . -delimited concatenation of the field names. It is used to represent a nested field. For example, in the data

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

• Parameters

  field_names( Iterable [ str , **... ] ) – The list of field names.

• Returns

  The . -delimited field path.

• Return type

  str

google.cloud.firestore_v1.field_path.get_nested_value(field_path, data)

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 pathcan 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 ](types.md#google.cloud.firestore_v1.types.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)

Parse a field pathfrom 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)

Create a field pathfrom a list of nested field names.

A field pathis a . -delimited concatenation of the field names. It is used to represent a nested field. For example, in the data

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

• Parameters

  field_names( Iterable [ str , **... ] ) – The list of field names.

• Returns

  The . -delimited field path.

• Return type

  str

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

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.