o  iX@s0dZddlmZddlZddlmZmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZddlmZddlmZerddlmZdd lmZdd lmZmZdd lm Z dd l!m"Z"dd l#m$Z$ddl%m&Z&ddl'm(Z(ddl)m*Z*ddl+m,Z,ddl-m.Z.dZ/Gddde eZ0dddZ1dddZ2dS)zHClasses for representing collections for the Google Cloud Firestore API.) annotationsN) TYPE_CHECKINGAnyAsyncGenerator AsyncIterator Coroutine GeneratorGenericIterableSequenceTupleUnionOptional)retry)_helpers) QueryType)BaseAggregationQuery)DocumentSnapshot)BaseVectorQueryDistanceMeasure)DocumentReference) FieldPath)ExplainOptions)QueryResultsList)StreamGenerator) Transaction)Vector) VectorQuery>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789c@seZdZdZdwddZddZedd Zed d Zdxd dZ dyddZ dzddZ d{d|ddZ d}ddZ   d~dd%d&Z   d~dd(d)Z   d~dd-d.Z   d~dd0d1Zdxd2d3Zdd6d7Z   d~dd8dd;d<Zdd>d?ZddBdCZddDdEZddGdHZddKdLZddMdNZddOdPZddQdRZ  dddTdUZ   d~ddVdd\d]Z   d~ddVdd_d`ZdadbZ d{dcddZ!d{ddgdhZ"d{ddidjZ#dddkddudvZ$dS)BaseCollectionReferencea A reference to a collection in a Firestore database. The collection may already exist or this class can facilitate creation of documents within the collection. Args: path (Tuple[str, ...]): The components in the collection path. This is a series of strings representing each collection and sub-collection ID, as well as the document IDs for any documents that contain a sub-collection. kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a :class:`~google.cloud.firestore_v1.client.Client` if provided. It represents the client that created this collection reference. Raises: ValueError: if * the ``path`` is empty * there are an even number of elements * a collection ID in ``path`` is not a string * a document ID in ``path`` is not a string TypeError: If a keyword other than ``client`` is used. returnNonecOs6tj|dd||_|dd|_|rtd|ddS)NT) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargsr,/var/www/snowflake_co_dev_github/snow_flake_back_end_deploy/env/lib/python3.10/site-packages/google/cloud/firestore_v1/base_collection.py__init__Usz BaseCollectionReference.__init__cCs(t||jstS|j|jko|j|jkSN) isinstance __class__NotImplementedr%r')r)otherr,r,r-__eq__^s zBaseCollectionReference.__eq__cCs |jdS)zfThe collection identifier. Returns: str: The last component of the path. )r%r)r,r,r-idcs zBaseCollectionReference.idcCs,t|jdkr dS|jdd}|jj|S)aDocument that owns the current collection. Returns: Optional[:class:`~google.cloud.firestore_v1.document.DocumentReference`]: The parent document, if the current collection is not a top-level collection. Nr5)lenr%r'document)r) parent_pathr,r,r-parentls  zBaseCollectionReference.parentrcCtr/NotImplementedErrorr6r,r,r-_query{zBaseCollectionReference._queryrcCr=r/r>r6r,r,r-_aggregation_query~rAz*BaseCollectionReference._aggregation_queryrcCr=r/r>r6r,r,r- _vector_queryrAz%BaseCollectionReference._vector_queryN document_id Optional[str]rcCs6|durt}|jdr|j|fn|f}|jj|S)aCreate a sub-document underneath the current collection. Args: document_id (Optional[str]): The document identifier within the current collection. If not provided, will default to a random 20 character string composed of digits, uppercase and lowercase and letters. Returns: :class:`~google.cloud.firestore_v1.document.DocumentReference`: The child document. Nr)_auto_idr%r'r:)r)rD child_pathr,r,r-r:s  z BaseCollectionReference.documentTuple[Any, str]cCsD|j}|durtj|jjdf}n|j}tj||jf}||fS)arGet fully-qualified parent path and prefix for this collection. Returns: Tuple[str, str]: Pair of * the fully-qualified (with database and project) path to the parent of this collection (will either be the database path or a document path). * the prefix to a document in this collection. N documents)r<rDOCUMENT_PATH_DELIMITERjoinr'_database_string_document_pathr7)r) parent_docr;expected_prefixr,r,r- _parent_infos  z$BaseCollectionReference._parent_info document_datadictr2retries.Retry | retries.AsyncRetry | object | NonetimeoutOptional[float]Tuple[DocumentReference, dict]cCs,|durt}||}t||}||fS)z+Shared setup for async / sync :method:`add`N)rFr:rmake_retry_timeout_kwargs)r)rQrDrrT document_refr+r,r,r- _prep_adds   z!BaseCollectionReference._prep_add)r)rQrDrrTr,r,r-addszBaseCollectionReference.add page_size Optional[int]Tuple[dict, dict]cCs6|\}}||j|dddid}t||}||fS)z6Shared setup for async / sync :method:`list_documents`T field_pathsN)r< collection_idr\ show_missingmask)rPr7rrW)r)r\rrTr<_requestr+r,r,r-_prep_list_documentss  z,BaseCollectionReference._prep_list_documentsUUnion[Generator[DocumentReference, Any, Any], AsyncGenerator[DocumentReference, Any]]cCr=r/r>)r)r\rrTr,r,r-list_documentsz&BaseCollectionReference.list_documentscCs |Sr/)r@ recursiver6r,r,r-ris z!BaseCollectionReference.recursiver_ Iterable[str]cC|}||S)aCreate a "select" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.select` for more information on this method. Args: field_paths (Iterable[str, ...]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the query results. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A "projected" query. )r@select)r)r_queryr,r,r-rls zBaseCollectionReference.selectfilter field_path op_stringcCsz|}|r7|r7|durtd|dkr0|dkr0g}|D]}t|tr(||}||q|}||||S|j|dS)aCreate a "where" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.where` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) for the field to filter on. Optional. op_string (str): A comparison operation in the form of a string. Acceptable values are ``<``, ``<=``, ``==``, ``>=``, ``>``, and ``in``. Optional. value (Any): The value to compare the field against in the filter. If ``value`` is :data:`None` or a NaN, then ``==`` is the only allowed operation. If ``op_string`` is ``in``, ``value`` must be a sequence of values. Optional. filter (class:`~google.cloud.firestore_v1.base_query.BaseFilter`): an instance of a Filter. Either a FieldFilter or a CompositeFilter. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A filtered query. Raises: ValueError, if both the positional arguments (field_path, op_string, value) and the filter keyword argument are passed at the same time. NzICan't pass in both the positional arguments and 'filter' at the same time__name__inrn)r@ ValueErrorr0strr:appendwhere)r)rprqvaluerorm wrapped_namesnamer,r,r-rws!    zBaseCollectionReference.whererucKs|}|j|fi|S)aCreate an "order by" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.order_by` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) on which to order the query results. kwargs (Dict[str, Any]): The keyword arguments to pass along to the query. The only supported keyword is ``direction``, see :meth:`~google.cloud.firestore_v1.query.Query.order_by` for more information. Returns: :class:`~google.cloud.firestore_v1.query.Query`: An "order by" query. )r@order_by)r)rpr+rmr,r,r-r{4sz BaseCollectionReference.order_bycountintcCrk)a-Create a limited query with this collection as parent. .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit` will drop previously set `limit_to_last`. See :meth:`~google.cloud.firestore_v1.query.Query.limit` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A limited query. )r@limitr)r|rmr,r,r-r~Js zBaseCollectionReference.limitcCrk)aDCreate a limited to last query with this collection as parent. .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit_to_last` will drop previously set `limit`. See :meth:`~google.cloud.firestore_v1.query.Query.limit_to_last` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A limited to last query. )r@ limit_to_lastrr,r,r-r`s z%BaseCollectionReference.limit_to_last num_to_skipcCrk)aSkip to an offset in a query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.offset` for more information on this method. Args: num_to_skip (int): The number of results to skip at the beginning of query results. (Must be non-negative.) Returns: :class:`~google.cloud.firestore_v1.query.Query`: An offset query. )r@offset)r)rrmr,r,r-rus zBaseCollectionReference.offsetdocument_fields*Union[DocumentSnapshot, dict, list, tuple]cCrk)aStart query at a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.start_at` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r@start_atr)rrmr,r,r-r z BaseCollectionReference.start_atcCrk)aStart query after a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.start_after` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r@ start_afterrr,r,r-rrz#BaseCollectionReference.start_aftercCrk)aEnd query before a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.end_before` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r@ end_beforerr,r,r-rrz"BaseCollectionReference.end_beforecCrk)aEnd query at a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.end_at` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r@end_atrr,r,r-rrzBaseCollectionReference.end_atTuple[Any, dict]cCs|}t||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)r@rrW)r)rrTrmr+r,r,r-_prep_get_or_streams z+BaseCollectionReference._prep_get_or_stream)explain_options transactionOptional[Transaction]rOptional[ExplainOptions]\QueryResultsList[DocumentSnapshot] | Coroutine[Any, Any, QueryResultsList[DocumentSnapshot]]cCr=r/r>r)rrrTrr,r,r-gets zBaseCollectionReference.getCStreamGenerator[DocumentSnapshot] | AsyncIterator[DocumentSnapshot]cCr=r/r>rr,r,r-streamrhzBaseCollectionReference.streamcCr=r/r>)r)callbackr,r,r- on_snapshotrAz#BaseCollectionReference.on_snapshotcCs|j|dS)z Adds a count over the nested query. :type alias: str :param alias: (Optional) The alias for the count alias)rBr|)r)rr,r,r-r|szBaseCollectionReference.count field_refstr | FieldPathcC|j||dS)a Adds a sum over the nested query. :type field_ref: Union[str, google.cloud.firestore_v1.field_path.FieldPath] :param field_ref: The field to aggregate across. :type alias: Optional[str] :param alias: Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_. r)rBsumr)rrr,r,r-rs zBaseCollectionReference.sumcCr)a Adds an avg over the nested query. :type field_ref: Union[str, google.cloud.firestore_v1.field_path.FieldPath] :param field_ref: The field to aggregate across. :type alias: Optional[str] :param alias: Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_. r)rBavgrr,r,r-rs zBaseCollectionReference.avgdistance_result_fielddistance_threshold vector_field query_vectorUnion[Vector, Sequence[float]]r~distance_measurerrrrcCs|j||||||dS)a Finds the closest vector embeddings to the given query vector. Args: vector_field (str): An indexed vector field to search upon. Only documents which contain vectors whose dimensionality match the query_vector can be returned. query_vector(Union[Vector, Sequence[float]]): The query vector that we are searching on. Must be a vector of no more than 2048 dimensions. limit (int): The number of nearest neighbors to return. Must be a positive integer of no more than 1000. distance_measure (:class:`DistanceMeasure`): The Distance Measure to use. distance_result_field (Optional[str]): Name of the field to output the result of the vector distance calculation distance_threshold (Optional[float]): A threshold for which no less similar documents will be returned. Returns: :class`~firestore_v1.vector_query.VectorQuery`: the vector query. r)rC find_nearest)r)rrr~rrrr,r,r-r,sz$BaseCollectionReference.find_nearest)r r!)r r)r r)r rr/)rDrEr r)r rH)NNN) rQrRrDrErrSrTrUr rV) rQrRrDrErrSrTrUr rZ)r\r]rrSrTrUr r^)r\r]rrSrTrUr rf)r_rjr r)rprErqrEr r)rprur r)r|r}r r)r|r})rr}r r)rrr r)NN)rrSrTrUr r) rrrrSrTrUrrr r) rrrrSrTrUrrr r)rr)rrurrr~r}rrrrErrUr r)%rr __module__ __qualname____doc__r.r4propertyr7r<r@rBrCr:rPrYr[rergrirlrwr{r~rrrrrrrrrrr|rrrr,r,r,r-r;s               5           rr rucCsdddtdDS)zGenerate a "random" automatically generated ID. Returns: str: A 20 character string composed of digits, uppercase and lowercase and letters. css|]}ttVqdSr/)randomchoice_AUTO_ID_CHARS).0rcr,r,r- Zsz_auto_id..)rKranger,r,r,r-rFRsrFrcCs|jtjd}||S)zConvert Document resource to document ref. Args: collection_reference (google.api_core.page_iterator.GRPCIterator): iterator response item (dict): document resource r5)rzsplitrrJr:)collection_referenceitemrDr,r,r-_item_to_document_ref]s r)r ru)r r)3r __future__rrtypingrrrrrrr r r r r rgoogle.api_corerretriesgoogle.cloud.firestore_v1r$google.cloud.firestore_v1.base_queryr*google.cloud.firestore_v1.base_aggregationr'google.cloud.firestore_v1.base_documentr+google.cloud.firestore_v1.base_vector_queryrr"google.cloud.firestore_v1.documentr$google.cloud.firestore_v1.field_pathr'google.cloud.firestore_v1.query_profiler'google.cloud.firestore_v1.query_resultsr*google.cloud.firestore_v1.stream_generatorr%google.cloud.firestore_v1.transactionr google.cloud.firestore_v1.vectorr&google.cloud.firestore_v1.vector_queryrrrrFrr,r,r,r-s6 8