valkey-glide 1.3.5rc2__pp39-pypy39_pp73-macosx_10_7_x86_64.whl

glide/async_commands/server_modules/ft.py

@@ -0,0 +1,395 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+"""
+module for `vector search` commands.
+"""
+
+from typing import List, Mapping, Optional, cast
+
+from glide.async_commands.server_modules.ft_options.ft_aggregate_options import (
+    FtAggregateOptions,
+)
+from glide.async_commands.server_modules.ft_options.ft_constants import (
+    CommandNames,
+    FtCreateKeywords,
+)
+from glide.async_commands.server_modules.ft_options.ft_create_options import (
+    Field,
+    FtCreateOptions,
+)
+from glide.async_commands.server_modules.ft_options.ft_profile_options import (
+    FtProfileOptions,
+)
+from glide.async_commands.server_modules.ft_options.ft_search_options import (
+    FtSearchOptions,
+)
+from glide.constants import (
+    TOK,
+    FtAggregateResponse,
+    FtInfoResponse,
+    FtProfileResponse,
+    FtSearchResponse,
+    TEncodable,
+)
+from glide.glide_client import TGlideClient
+
+
+async def create(
+    client: TGlideClient,
+    index_name: TEncodable,
+    schema: List[Field],
+    options: Optional[FtCreateOptions] = None,
+) -> TOK:
+    """
+    Creates an index and initiates a backfill of that index.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name.
+        schema (List[Field]): Fields to populate into the index. Equivalent to `SCHEMA` block in the module API.
+        options (Optional[FtCreateOptions]): Optional arguments for the FT.CREATE command.
+
+    Returns:
+        TOK: A simple "OK" response.
+
+    Examples:
+        >>> from glide import ft
+        >>> schema: List[Field] = [TextField("title")]
+        >>> prefixes: List[str] = ["blog:post:"]
+        >>> await ft.create(glide_client, "my_idx1", schema, FtCreateOptions(DataType.HASH, prefixes))
+            'OK'  # Indicates successful creation of index named 'idx'
+    """
+    args: List[TEncodable] = [CommandNames.FT_CREATE, index_name]
+    if options:
+        args.extend(options.to_args())
+    if schema:
+        args.append(FtCreateKeywords.SCHEMA)
+        for field in schema:
+            args.extend(field.to_args())
+    return cast(TOK, await client.custom_command(args))
+
+
+async def dropindex(client: TGlideClient, index_name: TEncodable) -> TOK:
+    """
+    Drops an index. The index definition and associated content are deleted. Keys are unaffected.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name for the index to be dropped.
+
+    Returns:
+        TOK: A simple "OK" response.
+
+    Examples:
+        For the following example to work, an index named 'idx' must be already created. If not created, you will get an error.
+        >>> from glide import ft
+        >>> index_name = "idx"
+        >>> await ft.dropindex(glide_client, index_name)
+            'OK'  # Indicates successful deletion/dropping of index named 'idx'
+    """
+    args: List[TEncodable] = [CommandNames.FT_DROPINDEX, index_name]
+    return cast(TOK, await client.custom_command(args))
+
+
+async def list(client: TGlideClient) -> List[TEncodable]:
+    """
+    Lists all indexes.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+
+    Returns:
+        List[TEncodable]: An array of index names.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.list(glide_client)
+            [b"index1", b"index2"]
+    """
+    return cast(List[TEncodable], await client.custom_command([CommandNames.FT_LIST]))
+
+
+async def search(
+    client: TGlideClient,
+    index_name: TEncodable,
+    query: TEncodable,
+    options: Optional[FtSearchOptions],
+) -> FtSearchResponse:
+    """
+    Uses the provided query expression to locate keys within an index. Once located, the count and/or the content of indexed fields within those keys can be returned.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name to search into.
+        query (TEncodable): The text query to search.
+        options (Optional[FtSearchOptions]): The search options.
+
+    Returns:
+        FtSearchResponse: A two element array, where first element is count of documents in result set, and the second element, which has the format Mapping[TEncodable, Mapping[TEncodable, TEncodable]] is a mapping between document names and map of their attributes.
+        If count(option in `FtSearchOptions`) is set to true or limit(option in `FtSearchOptions`) is set to FtSearchLimit(0, 0), the command returns array with only one element - the count of the documents.
+
+    Examples:
+        For the following example to work the following must already exist:
+        - An index named "idx", with fields having identifiers as "a" and "b" and prefix as "{json:}"
+        - A key named {json:}1 with value {"a":1, "b":2}
+
+        >>> from glide import ft
+        >>> await ft.search(glide_client, "idx", "*", options=FtSeachOptions(return_fields=[ReturnField(field_identifier="first"), ReturnField(field_identifier="second")]))
+        [1, { b'json:1': { b'first': b'42', b'second': b'33' } }] # The first element, 1 is the number of keys returned in the search result. The second element is a map of data queried per key.
+    """
+    args: List[TEncodable] = [CommandNames.FT_SEARCH, index_name, query]
+    if options:
+        args.extend(options.to_args())
+    return cast(FtSearchResponse, await client.custom_command(args))
+
+
+async def aliasadd(
+    client: TGlideClient, alias: TEncodable, index_name: TEncodable
+) -> TOK:
+    """
+    Adds an alias for an index. The new alias name can be used anywhere that an index name is required.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        alias (TEncodable): The alias to be added to an index.
+        index_name (TEncodable): The index name for which the alias has to be added.
+
+    Returns:
+        TOK: A simple "OK" response.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.aliasadd(glide_client, "myalias", "myindex")
+            'OK'  # Indicates the successful addition of the alias named "myalias" for the index.
+    """
+    args: List[TEncodable] = [CommandNames.FT_ALIASADD, alias, index_name]
+    return cast(TOK, await client.custom_command(args))
+
+
+async def aliasdel(client: TGlideClient, alias: TEncodable) -> TOK:
+    """
+    Deletes an existing alias for an index.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        alias (TEncodable): The existing alias to be deleted for an index.
+
+    Returns:
+        TOK: A simple "OK" response.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.aliasdel(glide_client, "myalias")
+            'OK'  # Indicates the successful deletion of the alias named "myalias"
+    """
+    args: List[TEncodable] = [CommandNames.FT_ALIASDEL, alias]
+    return cast(TOK, await client.custom_command(args))
+
+
+async def aliasupdate(
+    client: TGlideClient, alias: TEncodable, index_name: TEncodable
+) -> TOK:
+    """
+    Updates an existing alias to point to a different physical index. This command only affects future references to the alias.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        alias (TEncodable): The alias name. This alias will now be pointed to a different index.
+        index_name (TEncodable): The index name for which an existing alias has to updated.
+
+    Returns:
+        TOK: A simple "OK" response.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.aliasupdate(glide_client, "myalias", "myindex")
+            'OK'  # Indicates the successful update of the alias to point to the index named "myindex"
+    """
+    args: List[TEncodable] = [CommandNames.FT_ALIASUPDATE, alias, index_name]
+    return cast(TOK, await client.custom_command(args))
+
+
+async def info(client: TGlideClient, index_name: TEncodable) -> FtInfoResponse:
+    """
+    Returns information about a given index.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name for which the information has to be returned.
+
+    Returns:
+        FtInfoResponse: Nested maps with info about the index. See example for more details.
+
+    Examples:
+        An index with name 'myIndex', 1 text field and 1 vector field is already created for gettting the output of this example.
+        >>> from glide import ft
+        >>> await ft.info(glide_client, "myIndex")
+            [
+                b'index_name',
+                b'myIndex',
+                b'creation_timestamp', 1729531116945240,
+                b'key_type', b'JSON',
+                b'key_prefixes', [b'key-prefix'],
+                b'fields', [
+                    [
+                        b'identifier', b'$.vec',
+                        b'field_name', b'VEC',
+                        b'type', b'VECTOR',
+                        b'option', b'',
+                        b'vector_params', [
+                            b'algorithm', b'HNSW', b'data_type', b'FLOAT32', b'dimension', 2, b'distance_metric', b'L2', b'initial_capacity', 1000, b'current_capacity', 1000, b'maximum_edges', 16, b'ef_construction', 200, b'ef_runtime', 10, b'epsilon', b'0.01'
+                        ]
+                    ],
+                    [
+                        b'identifier', b'$.text-field',
+                        b'field_name', b'text-field',
+                        b'type', b'TEXT',
+                        b'option', b''
+                    ]
+                ],
+                b'space_usage', 653351,
+                b'fulltext_space_usage', 0,
+                b'vector_space_usage', 653351,
+                b'num_docs', 0,
+                b'num_indexed_vectors', 0,
+                b'current_lag', 0,
+                b'index_status', b'AVAILABLE',
+                b'index_degradation_percentage', 0
+            ]
+    """
+    args: List[TEncodable] = [CommandNames.FT_INFO, index_name]
+    return cast(FtInfoResponse, await client.custom_command(args))
+
+
+async def explain(
+    client: TGlideClient, index_name: TEncodable, query: TEncodable
+) -> TEncodable:
+    """
+    Parse a query and return information about how that query was parsed.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name for which the query is written.
+        query (TEncodable): The search query, same as the query passed as an argument to FT.SEARCH.
+
+    Returns:
+        TEncodable: A string containing the parsed results representing the execution plan.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.explain(glide_client, indexName="myIndex", query="@price:[0 10]")
+            b'Field {\n  price\n  0\n  10\n}\n' # Parsed results.
+    """
+    args: List[TEncodable] = [CommandNames.FT_EXPLAIN, index_name, query]
+    return cast(TEncodable, await client.custom_command(args))
+
+
+async def explaincli(
+    client: TGlideClient, index_name: TEncodable, query: TEncodable
+) -> List[TEncodable]:
+    """
+    Same as the FT.EXPLAIN command except that the results are displayed in a different format. More useful with cli.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name for which the query is written.
+        query (TEncodable): The search query, same as the query passed as an argument to FT.SEARCH.
+
+    Returns:
+        List[TEncodable]: An array containing the execution plan.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.explaincli(glide_client, indexName="myIndex", query="@price:[0 10]")
+            [b'Field {', b'  price', b'  0', b'  10', b'}', b''] # Parsed results.
+    """
+    args: List[TEncodable] = [CommandNames.FT_EXPLAINCLI, index_name, query]
+    return cast(List[TEncodable], await client.custom_command(args))
+
+
+async def aggregate(
+    client: TGlideClient,
+    index_name: TEncodable,
+    query: TEncodable,
+    options: Optional[FtAggregateOptions],
+) -> FtAggregateResponse:
+    """
+    A superset of the FT.SEARCH command, it allows substantial additional processing of the keys selected by the query expression.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name for which the query is written.
+        query (TEncodable): The search query, same as the query passed as an argument to FT.SEARCH.
+        options (Optional[FtAggregateOptions]): The optional arguments for the command.
+
+    Returns:
+        FtAggregateResponse: An array containing a mapping of field name and associated value as returned after the last stage of the command.
+
+    Examples:
+        >>> from glide import ft
+        >>> await ft.aggregate(glide_client, "myIndex", "*", FtAggregateOptions(loadFields=["__key"], clauses=[GroupBy(["@condition"], [Reducer("COUNT", [], "bicycles")])]))
+            [{b'condition': b'refurbished', b'bicycles': b'1'}, {b'condition': b'new', b'bicycles': b'5'}, {b'condition': b'used', b'bicycles': b'4'}]
+    """
+    args: List[TEncodable] = [CommandNames.FT_AGGREGATE, index_name, query]
+    if options:
+        args.extend(options.to_args())
+    return cast(FtAggregateResponse, await client.custom_command(args))
+
+
+async def profile(
+    client: TGlideClient, index_name: TEncodable, options: FtProfileOptions
+) -> FtProfileResponse:
+    """
+    Runs a search or aggregation query and collects performance profiling information.
+
+    Args:
+        client (TGlideClient): The client to execute the command.
+        index_name (TEncodable): The index name
+        options (FtProfileOptions): Options for the command.
+
+    Returns:
+        FtProfileResponse: A two-element array. The first element contains results of query being profiled, the second element stores profiling information.
+
+    Examples:
+        >>> ftSearchOptions = FtSeachOptions(return_fields=[ReturnField(field_identifier="a", alias="a_new"), ReturnField(field_identifier="b", alias="b_new")])
+        >>> await ft.profile(glide_client, "myIndex", FtProfileOptions.from_query_options(query="*", queryOptions=ftSearchOptions))
+            [
+                [
+                    2,
+                    {
+                        b'key1': {
+                            b'a': b'11111',
+                            b'b': b'2'
+                        },
+                        b'key2': {
+                            b'a': b'22222',
+                            b'b': b'2'
+                        }
+                    }
+                ],
+                {
+                    b'all.count': 2,
+                    b'sync.time': 1,
+                    b'query.time': 7,
+                    b'result.count': 2,
+                    b'result.time': 0
+                }
+            ]
+    """
+    args: List[TEncodable] = [CommandNames.FT_PROFILE, index_name] + options.to_args()
+    return cast(FtProfileResponse, await client.custom_command(args))
+
+
+async def aliaslist(client: TGlideClient) -> Mapping[TEncodable, TEncodable]:
+    """
+    List the index aliases.
+    Args:
+        client (TGlideClient): The client to execute the command.
+    Returns:
+        Mapping[TEncodable, TEncodable]: A map of index aliases for indices being aliased.
+    Examples:
+        >>> from glide import ft
+        >>> await ft._aliaslist(glide_client)
+            {b'alias': b'index1', b'alias-bytes': b'index2'}
+    """
+    args: List[TEncodable] = [CommandNames.FT_ALIASLIST]
+    return cast(Mapping, await client.custom_command(args))

glide/async_commands/server_modules/ft_options/ft_aggregate_options.py

@@ -0,0 +1,293 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import List, Mapping, Optional
+
+from glide.async_commands.command_args import OrderBy
+from glide.async_commands.server_modules.ft_options.ft_constants import (
+    FtAggregateKeywords,
+)
+from glide.constants import TEncodable
+
+
+class FtAggregateClause(ABC):
+    """
+    Abstract base class for the FT.AGGREGATE command clauses.
+    """
+
+    @abstractmethod
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the clause of the FT.AGGREGATE command.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the clause of the FT.AGGREGATE command.
+        """
+        args: List[TEncodable] = []
+        return args
+
+
+class FtAggregateLimit(FtAggregateClause):
+    """
+    A clause for limiting the number of retained records.
+    """
+
+    def __init__(self, offset: int, count: int):
+        """
+        Initialize a new FtAggregateLimit instance.
+
+        Args:
+            offset (int): Starting point from which the records have to be retained.
+            count (int): The total number of records to be retained.
+        """
+        self.offset = offset
+        self.count = count
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Limit clause.
+
+        Returns:
+            List[TEncodable]: A list of Limit clause arguments.
+        """
+        return [FtAggregateKeywords.LIMIT, str(self.offset), str(self.count)]
+
+
+class FtAggregateFilter(FtAggregateClause):
+    """
+    A clause for filtering the results using predicate expression relating to values in each result. It is applied post query and relate to the current state of the pipeline.
+    """
+
+    def __init__(self, expression: TEncodable):
+        """
+        Initialize a new FtAggregateFilter instance.
+
+        Args:
+            expression (TEncodable): The expression to filter the results.
+        """
+        self.expression = expression
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Filter clause.
+
+        Returns:
+            List[TEncodable]: A list arguments for the filter clause.
+        """
+        return [FtAggregateKeywords.FILTER, self.expression]
+
+
+class FtAggregateReducer:
+    """
+    A clause for reducing the matching results in each group using a reduction function. The matching results are reduced into a single record.
+    """
+
+    def __init__(
+        self,
+        function: TEncodable,
+        args: List[TEncodable],
+        name: Optional[TEncodable] = None,
+    ):
+        """
+        Initialize a new FtAggregateReducer instance.
+
+        Args:
+            function (TEncodable): The reduction function names for the respective group.
+            args (List[TEncodable]): The list of arguments for the reducer.
+            name (Optional[TEncodable]): User defined property name for the reducer.
+        """
+        self.function = function
+        self.args = args
+        self.name = name
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Reducer.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the reducer.
+        """
+        args: List[TEncodable] = [
+            FtAggregateKeywords.REDUCE,
+            self.function,
+            str(len(self.args)),
+        ] + self.args
+        if self.name:
+            args.extend([FtAggregateKeywords.AS, self.name])
+        return args
+
+
+class FtAggregateGroupBy(FtAggregateClause):
+    """
+    A clause for grouping the results in the pipeline based on one or more properties.
+    """
+
+    def __init__(
+        self, properties: List[TEncodable], reducers: List[FtAggregateReducer]
+    ):
+        """
+        Initialize a new FtAggregateGroupBy instance.
+
+        Args:
+            properties (List[TEncodable]): The list of properties to be used for grouping the results in the pipeline.
+            reducers (List[Reducer]): The list of functions that handles the group entries by performing multiple aggregate operations.
+        """
+        self.properties = properties
+        self.reducers = reducers
+
+    def to_args(self) -> List[TEncodable]:
+        args = [
+            FtAggregateKeywords.GROUPBY,
+            str(len(self.properties)),
+        ] + self.properties
+        if self.reducers:
+            for reducer in self.reducers:
+                args.extend(reducer.to_args())
+        return args
+
+
+class FtAggregateSortProperty:
+    """
+    This class represents the a single property for the SortBy clause.
+    """
+
+    def __init__(self, property: TEncodable, order: OrderBy):
+        """
+        Initialize a new FtAggregateSortProperty instance.
+
+        Args:
+            property (TEncodable): The sorting parameter.
+            order (OrderBy): The order for the sorting. This option can be added for each property.
+        """
+        self.property = property
+        self.order = order
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the SortBy clause property.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the SortBy clause property.
+        """
+        return [self.property, self.order.value]
+
+
+class FtAggregateSortBy(FtAggregateClause):
+    """
+    A clause for sorting the pipeline up until the point of SORTBY, using a list of properties.
+    """
+
+    def __init__(
+        self, properties: List[FtAggregateSortProperty], max: Optional[int] = None
+    ):
+        """
+        Initialize a new FtAggregateSortBy instance.
+
+        Args:
+            properties (List[FtAggregateSortProperty]): A list of sorting parameters for the sort operation.
+            max: (Optional[int]): The MAX value for optimizing the sorting, by sorting only for the n-largest elements.
+        """
+        self.properties = properties
+        self.max = max
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the SortBy clause.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the SortBy clause.
+        """
+        args: List[TEncodable] = [
+            FtAggregateKeywords.SORTBY,
+            str(len(self.properties) * 2),
+        ]
+        for property in self.properties:
+            args.extend(property.to_args())
+        if self.max:
+            args.extend([FtAggregateKeywords.MAX, str(self.max)])
+        return args
+
+
+class FtAggregateApply(FtAggregateClause):
+    """
+    A clause for applying a 1-to-1 transformation on one or more properties and stores the result as a new property down the pipeline or replaces any property using this transformation.
+    """
+
+    def __init__(self, expression: TEncodable, name: TEncodable):
+        """
+        Initialize a new FtAggregateApply instance.
+
+        Args:
+            expression (TEncodable): The expression to be transformed.
+            name (TEncodable): The new property name to store the result of apply. This name can be referenced by further APPLY/SORTBY/GROUPBY/REDUCE operations down the pipeline.
+        """
+        self.expression = expression
+        self.name = name
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the arguments for the Apply clause.
+
+        Returns:
+            List[TEncodable]: A list of arguments for the Apply clause.
+        """
+        return [
+            FtAggregateKeywords.APPLY,
+            self.expression,
+            FtAggregateKeywords.AS,
+            self.name,
+        ]
+
+
+class FtAggregateOptions:
+    """
+    This class represents the optional arguments for the FT.AGGREGATE command.
+    """
+
+    def __init__(
+        self,
+        loadAll: Optional[bool] = False,
+        loadFields: Optional[List[TEncodable]] = [],
+        timeout: Optional[int] = None,
+        params: Optional[Mapping[TEncodable, TEncodable]] = {},
+        clauses: Optional[List[FtAggregateClause]] = [],
+    ):
+        """
+        Initialize a new FtAggregateOptions instance.
+
+        Args:
+            loadAll (Optional[bool]): An option to load all fields declared in the index.
+            loadFields (Optional[List[TEncodable]]): An option to load only the fields passed in this list.
+            timeout (Optional[int]): Overrides the timeout parameter of the module.
+            params (Optional[Mapping[TEncodable, TEncodable]]): The key/value pairs can be referenced from within the query expression.
+            clauses (Optional[List[FtAggregateClause]]): FILTER, LIMIT, GROUPBY, SORTBY and APPLY clauses, that can be repeated multiple times in any order and be freely intermixed. They are applied in the order specified, with the output of one clause feeding the input of the next clause.
+        """
+        self.loadAll = loadAll
+        self.loadFields = loadFields
+        self.timeout = timeout
+        self.params = params
+        self.clauses = clauses
+
+    def to_args(self) -> List[TEncodable]:
+        """
+        Get the optional arguments for the FT.AGGREGATE command.
+
+        Returns:
+            List[TEncodable]: A list of optional arguments for the FT.AGGREGATE command.
+        """
+        args: List[TEncodable] = []
+        if self.loadAll:
+            args.extend([FtAggregateKeywords.LOAD, "*"])
+        elif self.loadFields:
+            args.extend([FtAggregateKeywords.LOAD, str(len(self.loadFields))])
+            args.extend(self.loadFields)
+        if self.timeout:
+            args.extend([FtAggregateKeywords.TIMEOUT, str(self.timeout)])
+        if self.params:
+            args.extend([FtAggregateKeywords.PARAMS, str(len(self.params) * 2)])
+            for [name, value] in self.params.items():
+                args.extend([name, value])
+        if self.clauses:
+            for clause in self.clauses:
+                args.extend(clause.to_args())
+        return args