io.github.honhimw.ms.api.Indexes Maven / Gradle / Ivy

Go to download
/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.github.honhimw.ms.api;

import io.github.honhimw.ms.json.TypeRef;
import io.github.honhimw.ms.model.*;
import io.swagger.v3.oas.annotations.Operation;
import jakarta.annotation.Nullable;

import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * An index is an entity that gathers a set of documents with its own settings. Learn more about indexes.
 *
 * @author hon_him
 * @since 2023-12-29
 */

public interface Indexes {

    /**
     * List all indexes
     *
     * @param offset Number of indexes to skip
     * @param limit  Number of indexes to return
     */
    @Operation(method = "GET", tags = "/indexes")
    Page list(@Nullable Integer offset, @Nullable Integer limit);

    @Operation(method = "GET", tags = "/indexes")
    Page list(Consumer page);

    @Operation(method = "GET", tags = "/indexes")
    Page list(PageRequest page);

    /**
     * Get information about an index.
     *
     * @param uid uid of the requested index
     */
    @Operation(method = "GET", tags = "/indexes/{index_uid}")
    Optional get(String uid);

    /**
     * Create an index.
     *
     * @param uid        uid of the requested index
     * @param primaryKey Primary key of the requested index
     * @return create task
     */
    @Operation(method = "POST", tags = "/indexes")
    TaskInfo create(String uid, @Nullable String primaryKey);

    @Operation(method = "POST", tags = "/indexes")
    TaskInfo create(String uid);

    /**
     * Update an index. Specify a primaryKey if it doesn't already exists yet.
     *
     * @param uid uid of the requested index
     * @return update task
     */
    @Operation(method = "PATCH", tags = "/indexes/{index_uid}")
    TaskInfo update(String uid, String primaryKey);

    /**
     * Delete an index.
     *
     * @param uid uid of the requested index
     * @return delete task
     */
    @Operation(method = "DELETE", tags = "/indexes/{index_uid}")
    TaskInfo delete(String uid);

    /**
     * Deploy a new version of an index without any downtime for clients by swapping documents,
     * settings, and task history between two indexes.
     * Specifying several swap operations that will be processed in an atomic way is possible.
     *
     * @param uids Array of the two indexUids to be swapped
     * @return indexSwap
     */
    @Operation(method = "POST", tags = "/swap-indexes")
    TaskInfo swap(List> uids);

    /**
     * @param consumer entryList configurer
     * @see #swap(List)
     */
    @Operation(method = "POST", tags = "/swap-indexes")
    TaskInfo swap(Consumer consumer);

    /**
     * Get the operator for a single index.
     * @param uid index uid
     * @return {@link SingleIndex} operator
     */
    SingleIndex single(String uid);

    /**
     * Documents are objects composed of fields that can store any type of data.
     * Each field contains an attribute and its associated value.
     * Documents are stored inside indexes.
     * Learn more about documents.
     *
     * @param uid uid of the requested index
     * @return {@link Documents} operator
     */
    @Operation(tags = "/indexes/{index_uid}/documents")
    Documents documents(String uid);

     R documents(String uid, Function operation);

     TypedDocuments documents(String uid, TypeRef typeRef);

     TypedDocuments documents(String uid, Class type);

     R documents(String uid, TypeRef typeRef, Function, R> operation);

     R documents(String uid, Class type, Function, R> operation);

    /**
     * Meilisearch exposes 3 routes to perform document searches:
     * 
     *     A POST route: this is the preferred route when using API authentication, as it allows preflight request caching and better performances.
     *     A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example). Other than the differences mentioned above, the two routes are strictly equivalent.
     *     A POST multi-search route allowing to perform multiple search queries in a single HTTP request. Meilisearch exposes 1 route to perform facet searches:
     *     A POST facet-search route allowing to perform a facet search query on a facet in a single HTTP request.
     * 
     *
     * @param uid uid of the requested index
     * @return {@link Search} operator
     */
    @Operation(tags = "/indexes/{index_uid}/search")
    Search search(String uid);

     R search(String uid, Function operation);

     TypedSearch search(String uid, TypeRef typeRef);

     TypedSearch search(String uid, Class type);

     R search(String uid, TypeRef typeRef, Function, R> operation);

     R search(String uid, Class type, Function, R> operation);

     TypedDetailsSearch searchWithDetails(String uid, TypeRef typeRef);

     TypedDetailsSearch searchWithDetails(String uid, Class type);

     R searchWithDetails(String uid, TypeRef typeRef, Function, R> operation);

     R searchWithDetails(String uid, Class type, Function, R> operation);

    @Operation(tags = "/indexes/{indexUid}/settings")
    Settings settings(String uid);

     R settings(String uid, Function operation);

    /**
     * Get stats of all indexes.
     *
     * @return stats of all indexes.
     */
    @Operation(method = "GET", tags = "/stats")
    Stats stats();

    /**
     * Get stats of an index.
     *
     * @return stats of an index.
     */
    @Operation(method = "GET", tags = "/indexes/{index_uid}/stats")
    IndexStats stats(String uid);

}