tech.ydb.yoj.repository.ydb.statement.Statement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of yoj-repository-ydb-v2 Show documentation
YOJ (YDB ORM for Java) Repository API implementation for YDB. Uses YDB SDK v2.x.
The newest version!
package tech.ydb.yoj.repository.ydb.statement;

import tech.ydb.proto.ValueProtos;
import tech.ydb.yoj.repository.db.cache.RepositoryCache;
import tech.ydb.yoj.repository.ydb.YdbRepositoryTransaction;

import java.util.List;
import java.util.Map;

/**
 * Represents a statement that can be executed in a {@link YdbRepositoryTransaction}.
 *
 * @param  type holding the statement's parameters
 * @param  statement result type
 */
public interface Statement {
    // YQL

    /**
     * Tells whether the statement should be prepared, that is, parsed once and then cached for subsequent
     * queries during the same session.

     * Prepared statements offer better query performance, but consume additional memory.
     * 
     * You should not blindly prepare all statements, especially non-parameterized ones; so by default this method
     * returns {@code false}.
     *
     * @return {@code true} if the statement should be prepared; {@code false} otherwise
     */
    default boolean isPreparable() {
        return false;
    }

    /**
     * Returns parameterized YQL for this query.
     *
     * @param tablespace base path for all tables referenced in the query
     * @return YQL
     */
    String getQuery(String tablespace);

    /**
     * Returns debug representation of this query with the specified parameter values.
     *
     * @param params parameter values.
     *               Might be {@code null} depending on the statement type, e.g. for DELETE statements.
     * @return debug representation of the query parameterized with {@code params}
     */
    String toDebugString(PARAMS params);

    // Parameters

    /**
     * Returns the query's parameter values as YDB protobuf structures.
     *
     * @param params parameter values
     *               Might be {@code null} depending on the statement type, e.g. for DELETE statements.
     * @return map: parameter name -> value as protobuf
     */
    Map toQueryParameters(PARAMS params);

    // Results

    /**
     * Converts YDB result set into the query result.
     *
     * @param columns result set as a YDB protobuf structure
     * @param value   result set as a YDB protobuf structure
     * @return query result
     */
    RESULT readResult(List columns, ValueProtos.Value value);

    // First level cache

    /**
     * Tries to read the query result from first-level cache.
     *
     * @param params parameter values.
     *               Might be {@code null} depending on the statement type, e.g. for DELETE statements.
     * @param cache  first-level cache
     * @return query result, if present in first-level cache; {@code null} otherwise
     */
    default List readFromCache(PARAMS params, RepositoryCache cache) {
        return null;
    }

    /**
     * Writes the query result to first-level cache.
     *
     * @param params parameter values
     *               Might be {@code null} depending on the statement type, e.g. for DELETE statements.
     * @param result result to save; if {@code null}, nothing will be saved to cache
     * @param cache  first-level cache
     */
    default void storeToCache(PARAMS params, List result, RepositoryCache cache) {
    }

    // Query Merging

    /**
     * Returns query type (for query merging purposes).
     *
     * @return query type
     */
    QueryType getQueryType();

    enum QueryType {
        UNTYPED,
        SELECT,
        INSERT,
        UPSERT,
        UPDATE,
        DELETE,
        DELETE_ALL
    }
}