Repository: apache/flink
File: flink-table/flink-table-common/src/main/java/org/apache/flink/table/connector/source/VectorSearchTableSource.java (Java)

Code before:
     * VectorSearchRuntimeProvider} serves as the base interface.
     *
     * <p>Independent of the provider interface, a source implementation can work on either
     * arbitrary objects or internal data structures (see {@link org.apache.flink.table.data} for
     * more information).
     *
     * <p>The given {@link VectorSearchContext} offers utilities by the planner for creating runtime
     * implementation with minimal dependencies to internal data structures.
     *
     * @see VectorSearchFunctionProvider
     * @see AsyncVectorSearchFunctionProvider
     */
    VectorSearchRuntimeProvider getSearchRuntimeProvider(VectorSearchContext context);

    // --------------------------------------------------------------------------------------------
    // Helper interfaces
    // --------------------------------------------------------------------------------------------

    /**
     * Context for creating runtime implementation via a {@link VectorSearchRuntimeProvider}.
     *
     * <p>It offers utilities by the planner for creating runtime implementation with minimal
     * dependencies to internal data structures.
     *
     * <p>Methods should be called in {@link #getSearchRuntimeProvider(VectorSearchContext)}.
     * Returned instances that are {@link Serializable} can be directly passed into the runtime
     * implementation class.
     */
    @PublicEvolving
    interface VectorSearchContext extends DynamicTableSource.Context {

        /**
         * Returns an array of key index paths that should be used during the search. The indices
         * are 0-based and support composite keys within (possibly nested) structures.
         *
         * <p>For example, given a table with data type {@code ROW < i INT, s STRING, r ROW < i2
         * INT, s2 STRING > >}, this method would return {@code [[0], [2, 1]]} when {@code i} and
         * {@code s2} are used for performing a lookup.
         *
         * @return array of key index paths
         */
        int[][] getSearchColumns();

        /**
         * Runtime config provided to provider. The config can be used by planner or vector search
         * provider at runtime. For example, async options can be used by planner to choose async
         * inference. Other config such as http timeout or retry can be used to configure search
         * functions.
         */
        ReadableConfig runtimeConfig();
    }

Review comment (suggestion):
I am not sure what "Methods should be called in " means. Maybe "classes needing access to the Vector search information should use {@link #getSearchRuntimeProvider(VectorSearchContext)}"

Code after:
     * <p>There exist different interfaces for runtime implementation which is why {@link
     * VectorSearchRuntimeProvider} serves as the base interface.
     *
     * <p>Independent of the provider interface, a source implementation can work on either
     * arbitrary objects or internal data structures (see {@link org.apache.flink.table.data} for
     * more information).
     *
     * <p>The given {@link VectorSearchContext} offers utilities for the planner to create runtime
     * implementation with minimal dependencies to internal data structures.
     *
     * @see VectorSearchFunctionProvider
     * @see AsyncVectorSearchFunctionProvider
     */
    VectorSearchRuntimeProvider getSearchRuntimeProvider(VectorSearchContext context);

    // --------------------------------------------------------------------------------------------
    // Helper interfaces
    // --------------------------------------------------------------------------------------------

    /**
     * Context for creating runtime implementation via a {@link VectorSearchRuntimeProvider}.
     *
     * <p>It offers utilities for the planner to create runtime implementation with minimal
     * dependencies to internal data structures.
     *
     * <p>Methods should be called in {@link #getSearchRuntimeProvider(VectorSearchContext)}.
     * Returned instances that are {@link Serializable} can be directly passed into the runtime
     * implementation class.
     */
    @PublicEvolving
    interface VectorSearchContext extends DynamicTableSource.Context {

        /**
         * Returns an array of key index paths that should be used during the search. The indices
         * are 0-based and support composite keys within (possibly nested) structures.
         *
         * <p>For example, given a table with data type {@code ROW < i INT, s STRING, r ROW < i2
         * INT, s2 STRING > >}, this method would return {@code [[0], [2, 1]]} when {@code i} and
         * {@code s2} are used for performing a lookup.
         *
         * @return array of key index paths
         */
        int[][] getSearchColumns();

        /**
         * Runtime config provided to the provider. The config can be used by the planner or vector
         * search provider at runtime. For example, async options can be used by planner to choose
         * async inference. Other config such as http timeout or retry can be used to configure
         * search functions.
         */
        ReadableConfig runtimeConfig();