o  i.X@s8dZddlmZddlmZmZmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZdd lmZdd lmZmZmZmZmZmZdd lmZerdd lm Z dd l!m"Z"ddl#m$Z$ddl%m&Z&ddl'm(Z(m)Z)ddl*m+mm,m-Z.ddl/m0Z0GdddeZ1Gddde1eZ2dS)a+Classes for representing queries for the Google Cloud Firestore API. A :class:`~google.cloud.firestore_v1.query.Query` can be created directly from a :class:`~google.cloud.firestore_v1.collection.Collection` and that can be a more common way to create a query than direct usage of the constructor. ) annotations) TYPE_CHECKINGAnyAsyncGeneratorListOptionalType)gapic_v1) retry_async) firestore_v1)AsyncAggregationQuery)AsyncStreamGenerator)AsyncVectorQuery)BaseCollectionGroup BaseQueryQueryPartition,_collection_group_query_response_to_snapshot_enum_from_direction_query_response_to_snapshot)QueryResultsList)AsyncTransaction)DocumentSnapshot)DistanceMeasure) FieldPath)ExplainMetricsExplainOptionsN)VectorcseZdZdZ          dd d Zdejjdfddd?ddZ dddd@d&d'Z dAdBd+d,Z dAdCd/d0Z dAdCd1d2Z dejjddfdDd4d5ZdejjdfdddEd7d8ZedFd:d;ZZS)G AsyncQuerya5 Represents a query to the Firestore API. Instances of this class are considered immutable: all methods that would modify an instance instead return a new instance. Args: parent (:class:`~google.cloud.firestore_v1.collection.CollectionReference`): The collection that this query applies to. projection (Optional[:class:`google.cloud.firestore_v1. query.StructuredQuery.Projection`]): A projection of document fields to limit the query results to. field_filters (Optional[Tuple[:class:`google.cloud.firestore_v1. query.StructuredQuery.FieldFilter`, ...]]): The filters to be applied in the query. orders (Optional[Tuple[:class:`google.cloud.firestore_v1. query.StructuredQuery.Order`, ...]]): The "order by" entries to use in the query. limit (Optional[int]): The maximum number of documents the query is allowed to return. offset (Optional[int]): The number of results to skip. start_at (Optional[Tuple[dict, bool]]): Two-tuple of : * a mapping of fields. Any field that is present in this mapping must also be present in ``orders`` * an ``after`` flag The fields and the flag combine to form a cursor used as a starting point in a query result set. If the ``after`` flag is :data:`True`, the results will start just after any documents which have fields matching the cursor, otherwise any matching documents will be included in the result set. When the query is formed, the document values will be used in the order given by ``orders``. end_at (Optional[Tuple[dict, bool]]): Two-tuple of: * a mapping of fields. Any field that is present in this mapping must also be present in ``orders`` * a ``before`` flag The fields and the flag combine to form a cursor used as an ending point in a query result set. If the ``before`` flag is :data:`True`, the results will end just before any documents which have fields matching the cursor, otherwise any matching documents will be included in the result set. When the query is formed, the document values will be used in the order given by ``orders``. all_descendants (Optional[bool]): When false, selects only collections that are immediate children of the `parent` specified in the containing `RunQueryRequest`. When true, selects all descendant collections. recursive (Optional[bool]): When true, returns all documents and all documents in any subcollections below them. Defaults to false. NFreturnNonec *tt|j||||||||| | | d dSN) parent projection field_filtersorderslimit limit_to_lastoffsetstart_atend_atall_descendants recursive)superr__init__ selfr#r$r%r&r'r(r)r*r+r,r- __class__r/var/www/snowflake_co_dev_github/snow_flake_back_end_deploy/env/lib/python3.10/site-packages/google/cloud/firestore_v1/async_query.pyr/p  zAsyncQuery.__init__ chunk_sizeint,AsyncGenerator[List[DocumentSnapshot], None]c Cs|j}d}|}d} |||}||}|r||}|IdH}|r,|d}|t|7}|Vt||ksA|rC||krCdSq )NrT)_limit_copy_resolve_chunk_sizer' start_aftergetlen) r1r6 max_to_return num_returnedoriginal last_document _chunk_size_q snapshotsrrr4 _chunkifys*     zAsyncQuery._chunkify)explain_options transactionOptional[AsyncTransaction]retry"retries.AsyncRetry | object | NonetimeoutOptional[float]rHOptional[ExplainOptions]"QueryResultsList[DocumentSnapshot]c sd}|j}|jr!|jD]}t|j|jkr|jn|j|_q d|_|j||||d}z)dd|2IdH} |r=tt| } |durDd}n| IdH}W| IdHn| IdHwt | ||S)aRead the documents in the collection that match this query. This sends a ``RunQuery`` RPC and returns a list of documents returned in the stream of ``RunQueryResponse`` messages. Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction.Transaction`]): An existing transaction that this query will run in. retry (Optional[google.api_core.retry.Retry]): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (Otional[float]): The timeout for this request. Defaults to a system-specified value. explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Returns: QueryResultsList[DocumentSnapshot]: The documents in the collection that match this query. NFrIrKrMrHcsg|z3dHW}|q6SNr).0drrr4 sz"AsyncQuery.get..) _limit_to_last_ordersr direction ASCENDING DESCENDINGstreamlistreversedget_explain_metricsacloser) r1rIrKrMrHexplain_metricsis_limited_to_lastorderresult result_listrrr4r>s6#     zAsyncQuery.get)distance_result_fielddistance_threshold vector_fieldstr query_vectorrr'distance_measurerre Optional[str]rfrcCst|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 (Vector): 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. If unset then the distance will not be returned. 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. )rgrir'rjrerf)r find_nearest)r1rgrir'rjrerfrrr4rlszAsyncQuery.find_nearestalias str | None. Returns: :class:`~google.cloud.firestore_v1.async_aggregation.AsyncAggregationQuery`: An instance of an AsyncAggregationQuery object rm)r count)r1rmrrr4rqs zAsyncQuery.count field_refstr | FieldPathcCt|j||dS)a.Adds a sum over the nested query. Args: field_ref(Union[str, google.cloud.firestore_v1.field_path.FieldPath]): The field to aggregate across. alias(Optional[str]): 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_. Returns: :class:`~google.cloud.firestore_v1.async_aggregation.AsyncAggregationQuery`: An instance of an AsyncAggregationQuery object rp)r sumr1rrrmrrr4ru-zAsyncQuery.sumcCrt)a/Adds an avg over the nested query. Args: field_ref(Union[str, google.cloud.firestore_v1.field_path.FieldPath]): The field to aggregate across. alias(Optional[str]): 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_. Returns: :class:`~google.cloud.firestore_v1.async_aggregation.AsyncAggregationQuery`: An instance of an AsyncAggregationQuery object rp)r avgrvrrr4rx=rwzAsyncQuery.avgGAsyncGenerator[DocumentSnapshot | query_profile_pb.ExplainMetrics, Any]c Cs|||||\}}}|jjjd||jjd|IdH}|2z'3dHW} |jr0t| |j} nt| |j|} | dur>| V| j rG| j } | Vq 6dS)aInternal method for stream(). Read the documents in the collection that match this query. This sends a ``RunQuery`` RPC and then returns a generator which consumes each document returned in the stream of ``RunQueryResponse`` messages. .. note:: The underlying stream of responses will time out after the ``max_rpc_timeout_millis`` value set in the GAPIC client configuration for the ``RunQuery`` API. Snapshots not consumed from the iterator before that point will be lost. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction. Transaction`]): An existing transaction that the query will run in. retry (Optional[google.api_core.retry.Retry]): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (Optional[float]): The timeout for this request. Defaults to a system-specified value. explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. Yields: [:class:`~google.cloud.firestore_v1.base_document.DocumentSnapshot` | google.cloud.firestore_v1.types.query_profile.ExplainMetrtics]: The next document that fulfills the query. Query results will be yielded as `DocumentSnapshot`. When the result contains returned explain metrics, yield `query_profile_pb.ExplainMetrics` individually. requestmetadataNr) _prep_stream_client_firestore_api run_query _rpc_metadata_all_descendantsr_parentrr`) r1rIrKrMrHr{expected_prefixkwargsresponse_iteratorresponsesnapshotmetricsrrr4 _make_streamMs8.  zAsyncQuery._make_stream&AsyncStreamGenerator[DocumentSnapshot]cCs|j||||d}t||S)aGRead the documents in the collection that match this query. This sends a ``RunQuery`` RPC and then returns a generator which consumes each document returned in the stream of ``RunQueryResponse`` messages. .. note:: The underlying stream of responses will time out after the ``max_rpc_timeout_millis`` value set in the GAPIC client configuration for the ``RunQuery`` API. Snapshots not consumed from the iterator before that point will be lost. If a ``transaction`` is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed). Args: transaction (Optional[:class:`~google.cloud.firestore_v1.transaction. Transaction`]): An existing transaction that the query will run in. retry (Optional[google.api_core.retry.Retry]): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (Optional[float]): The timeout for this request. Defaults to a system-specified value. explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.ExplainOptions`]): Options to enable query profiling for this query. When set, explain_metrics will be available on the returned generator. Returns: `AsyncStreamGenerator[DocumentSnapshot]`: An asynchronous generator of the queryresults. rQ)rr )r1rIrKrMrHinner_generatorrrr4r[s+ zAsyncQuery.stream>Type['firestore_v1.async_collection.AsyncCollectionReference']cCsddlm}|S)NrAsyncCollectionReference)*google.cloud.firestore_v1.async_collectionrrrrr4_get_collection_reference_classs z*AsyncQuery._get_collection_reference_class) NrrNFNNNFFrr )r6r7rr8) rIrJrKrLrMrNrHrOrrP)rgrhrirr'r7rjrrerkrfrNrrrR)rmrnrro)rrrsrmrnrro) rIrJrKrLrMrNrHrOrry) rIrJrKrLrMrNrHrOrr)rr)__name__ __module__ __qualname____doc__r/rGr methodDEFAULTr>rlrqrurxrr[ staticmethodr __classcell__rrr2r4r5sT= (M'    M3rcsXeZdZdZ          ddfdd Zed d Zejj dfdddZ Z S)AsyncCollectionGroupaRepresents a Collection Group in the Firestore API. This is a specialization of :class:`.AsyncQuery` that includes all documents in the database that are contained in a collection or subcollection of the given parent. Args: parent (:class:`~google.cloud.firestore_v1.collection.CollectionReference`): The collection that this query applies to. NrFTrr c r!r")r.rr/r0r2rr4r/r5zAsyncCollectionGroup.__init__cCstSrR)rrrrr4_get_query_classsz%AsyncCollectionGroup._get_query_classrKrLrM float | None$AsyncGenerator[QueryPartition, None]c Cs||||\}}|jjjd||jjd|IdH}d}|2z3dHW}|j|jdj} t||| V| }q 6t||dVdS)a Partition a query for parallelization. Partitions a query by returning partition cursors that can be used to run the query in parallel. The returned partition cursors are split points that can be used as starting/end points for the query results. Args: partition_count (int): The desired maximum number of partition points. The number must be strictly positive. The actual number of partitions returned may be fewer. retry (google.api_core.retry.Retry): Designation of what errors, if any, should be retried. Defaults to a system-specified policy. timeout (float): The timeout for this request. Defaults to a system-specified value. rzNrr) _prep_get_partitionsr~rpartition_queryrdocumentvaluesreference_valuer) r1partition_countrKrMr{rpagerr* cursor_pbcursorrrr4get_partitionss  z#AsyncCollectionGroup.get_partitions) NrrNFNNNTFr)rKrLrMrrr) rrrrr/rrr rrrrrrr2r4rs$ r)3r __future__rtypingrrrrrrgoogle.api_corer r retries google.cloudr +google.cloud.firestore_v1.async_aggregationr 0google.cloud.firestore_v1.async_stream_generatorr ,google.cloud.firestore_v1.async_vector_queryr$google.cloud.firestore_v1.base_queryrrrrrr'google.cloud.firestore_v1.query_resultsr+google.cloud.firestore_v1.async_transactionr'google.cloud.firestore_v1.base_documentr+google.cloud.firestore_v1.base_vector_queryr$google.cloud.firestore_v1.field_pathr'google.cloud.firestore_v1.query_profilerr-google.cloud.firestore_v1.types.query_profilecloudtypes query_profilequery_profile_pb google.cloud.firestore_v1.vectorrrrrrrr4s0               "