Quelle  fts0exec.h   Sprache: C

/*****************************************************************************

Copyright (c) 2025, MariaDB PLC.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA

*****************************************************************************/

/**************************************************//**
@file include/fts0exec.h
FTS Query Builder - Abstraction layer for FTS operations

Created 2025/10/30
*******************************************************/

#pragma once

#include "row0query.h"
#include "fts0fts.h"
#include "fts0types.h"
#include "fts0opt.h"
#include "fts0ast.h"
#include <functional>

/** Structure to represent FTS auxiliary table data for insertion */
struct fts_aux_data_t
{
  /**
  CREATE TABLE $FTS_PREFIX_INDEX_[1-6](
        word            VARCHAR(FTS_MAX_WORD_LEN),
        first_doc_id    INT NOT NULL,
        last_doc_id     UNSIGNED NOT NULL,
        doc_count       UNSIGNED INT NOT NULL,
        ilist           VARBINARY NOT NULL,
        UNIQUE CLUSTERED INDEX ON (word, first_doc_id));
  */
  const char *word;
  ulint      word_len;
  doc_id_t   first_doc_id;
  doc_id_t   last_doc_id;
  uint32_t   doc_count;
  const byte *ilist;
  ulint      ilist_len;

  fts_aux_data_t(const char *w, ulint w_len)
    : word(w), word_len(w_len)
  {
    first_doc_id= last_doc_id= doc_count= 0;
    ilist= nullptr;
    ilist_len= 0;
  }

  fts_aux_data_t(const char* w, ulint w_len, doc_id_t first_id,
                 doc_id_t last_id, uint32_t d_count, const byte *il,
                 ulint il_len)
    : word(w), word_len(w_len), first_doc_id(first_id),
      last_doc_id(last_id), doc_count(d_count), ilist(il),
      ilist_len(il_len) {}
};

/** FTS deletion table types for m_common_tables array indexing */
enum class FTSDeletionTable : uint8_t
{
  DELETED= 0,
  DELETED_CACHE= 1,
  BEING_DELETED= 2,
  BEING_DELETED_CACHE= 3,
  MAX_DELETION_TABLES= 4
};

/** Helper to convert FTSDeletionTable to array index */
constexpr uint8_t to_index(FTSDeletionTable table_type) noexcept
{
  return static_cast<uint8_t>(table_type);
}

/** Number of deletion tables */
constexpr uint8_t NUM_DELETION_TABLES = to_index(FTSDeletionTable::MAX_DELETION_TABLES);

/** Abstraction over QueryExecutor for FTS auxiliary/common tables.
Handles table open/lock and provides typed helpers to insert,
delete and read records in FTS INDEX_1..INDEX_6
and deletion tables (DELETED, BEING_DELETED, etc.) */
class FTSQueryExecutor
{
private:
  QueryExecutor m_executor;
  const dict_index_t *m_index;
  const dict_table_t *const m_table;
  /* FTS Auxiliary table pointers */
  dict_table_t *m_aux_tables[6]={nullptr};
  /* FTS deletion table pointers (DELETED, BEING_DELETED, etc.) */
  dict_table_t *m_common_tables[NUM_DELETION_TABLES]={nullptr};
  /* FTS CONFIG table pointer */
  dict_table_t *m_config_table={nullptr};

  /** Table preparation methods */

  /** Open FTS INDEX_[1..6] table for the given auxiliary index.
  @return DB_SUCCESS or error code */
  dberr_t open_aux_table(uint8_t aux_index) noexcept;

  /** Open a deletion table (DELETED, BEING_DELETED, etc.).
  @param table_type deletion table type
  @return DB_SUCCESS or error code */
  dberr_t open_deletion_table(FTSDeletionTable table_type) noexcept;

  /** Helper to convert deletion table enum to string name */
  static const char* get_deletion_table_name(
                       FTSDeletionTable table_type) noexcept;

  /** Table lock operation */

  /** Acquire a lock on an opened INDEX_[1..6] table.
  Retries lock wait once via QueryExecutor.
  @return DB_SUCCESS or error code */
  dberr_t lock_aux_tables(uint8_t aux_index, lock_mode mode) noexcept;

  /** Acquire a lock on an opened common FTS table.
  Retries lock wait once via QueryExecutor.
  @return DB_SUCCESS or error code */
  dberr_t lock_common_tables(uint8_t index, lock_mode mode) noexcept;

  /** Create search tuple for a word
  @param table   tuple to be created for this table
  @param word    word to create tuple for
  @param  heap   memory heap
  @return search tuple or nullptr if word is empty */
  dtuple_t* create_word_search_tuple(
    dict_table_t *table, const fts_string_t *word,
    mem_heap_t *heap) noexcept;
public:
  /** Open all auxiliary tables
  @return DB_SUCCESS or error code */
  dberr_t open_all_aux_tables(dict_index_t *fts_index) noexcept;

  /** Open all deletion tables (DELETED, BEING_DELETED, etc.)
  @return DB_SUCCESS or error code */
  dberr_t open_all_deletion_tables() noexcept;

  /** Open FTS CONFIG table for configuration operations.
  @return DB_SUCCESS or error code */
  dberr_t open_config_table() noexcept;

  /** Set CONFIG table directly (for cases where table is already opened).
  Each call acquires a reference, which the destructor releases.  A
  second set_config_table() would leak a reference (and leave the
  caller's pointer dangling at dtor time), so callers must ensure they
  set it at most once on a given executor.
  @param config_table CONFIG table pointer */
  void set_config_table(dict_table_t *config_table) noexcept
  {
    ut_ad(!m_config_table);
    m_config_table= config_table;
    m_config_table->acquire();
  }

  /** Create executor bound to trx and FTS table/index.
  @param trx transaction
  @param fts_table FTS table */
  FTSQueryExecutor(trx_t *trx, const dict_table_t *fts_table);

  /** Release any opened table handles and executor resources. */
  ~FTSQueryExecutor();

  /** High level DML operation on FTS TABLE */

  /** Insert a row into auxiliary INDEX_[1..6] table.
  Expects (word, first_doc_id, trx_id, roll_ptr, last_doc_id,
           doc_count, ilist).
  @param aux_index auxiliary table index
  @param aux_data  data to be inserted
  @return DB_SUCCESS or error code */
  dberr_t insert_aux_record(uint8_t aux_index,
                            const fts_aux_data_t *aux_data) noexcept;

  /** Insert a single doc_id into a common table (e.g. DELETED, ...)
  @param tbl_name  common table name
  @param doc_id    document id to be inserted
  @return DB_SUCCESS or error code */
  dberr_t insert_common_record(const char *tbl_name, doc_id_t doc_id) noexcept;

  /** Insert a key/value into CONFIG table.
  @param key key for the config table
  @param value value for the key
  @return DB_SUCCESS or error code */
  dberr_t insert_config_record(const char *key, const char *value) noexcept;

  /** Delete one word row from INDEX_[1..6] by (word).
  @param aux_index auxiliary table index
  @param aux_data  auxiliary table record
  @return DB_SUCCESS or error code */
  dberr_t delete_aux_record(uint8_t aux_index,
                            const fts_aux_data_t *aux_data) noexcept;

  /** Delete a single doc_id row from a common table by (doc_id).
  @param tbl_name common table name
  @param doc_id document id to be deleted
  @return DB_SUCCESS or error code */
  dberr_t delete_common_record(const char *tbl_name, doc_id_t doc_id) noexcept;

  /** Delete all rows from a common table.
  @return DB_SUCCESS or error code */
  dberr_t delete_all_common_records(const char *tbl_name) noexcept;

  /** Delete a key from CONFIG table by (key).
  @return DB_SUCCESS or error code */
  dberr_t delete_config_record(const char *key) noexcept;

  /** Upsert a key/value in CONFIG table.
  Replaces 'value' if key exists, inserts otherwise.
  @return DB_SUCCESS or error code */
  dberr_t update_config_record(const char *key, const char *value) noexcept;

  /** Select-for-update CONFIG row by 'key'
  @return DB_SUCCESS or error code */
  dberr_t read_config_with_lock(
    const char *key, RecordCallback &callback) noexcept;

  /** Read all rows from given COMMON table
  Callback is invoked for processing the record */
  dberr_t read_all_common(const char *tbl_name,
                          RecordCallback &callback) noexcept;
  mem_heap_t *get_heap() const noexcept
  { return m_executor.get_heap(); }

  trx_t *trx() const noexcept
  { return m_executor.get_trx(); }

  const dict_index_t* index() const noexcept
  { return m_index; }

  void release_lock()
  {
    m_executor.commit_mtr();
  }

  /** Read records by index using underlying QueryExecutor
  @param table table to read
  @param sec_index secondary index
  @param search_tuple search tuple
  @param mode cursor mode
  @param callback record callback
  @return DB_SUCCESS or error code */
  dberr_t read_by_index(dict_table_t *table, dict_index_t *index,
                        const dtuple_t *search_tuple, page_cur_mode_t mode,
                        RecordCallback& callback) noexcept
  { 
    dberr_t err= m_executor.read_by_index(table, index, search_tuple,
                                          mode, callback, true);
    return (err == DB_SUCCESS_LOCKED_REC) ? DB_SUCCESS : err;
  }

  /** Construct FTS auxiliary table name
  @param table_name output buffer for table name
  @param suffix table suffix (e.g., "CONFIG", "INDEX_1")
  @param common_table true for common tables, false for index tables */
  void construct_table_name(char *table_name, const char *suffix,
                            bool common_table) noexcept;

  dberr_t read_aux(uint8_t aux_index,
                 const fts_string_t* start_word,
                 RecordCallback& callback) noexcept;
};

/** Callback class for reading common table records
(DELETED, BEING_DELETED, DELETED_CACHE, BEING_DELETED_CACHE) */
class CommonTableReader : public RecordCallback
{
private:
  /** Heap owning m_doc_ids when this reader allocates
  its own vector; */
  mem_heap_t *m_heap;
  /** Destination for extracted doc_ids */
  ib_vector_t *m_doc_ids;

  /** Build the row consumer shared by both constructors.
  @return processor appending each extracted doc_id to m_doc_ids */
  RecordProcessor make_processor();

public:
  /** Accumulate doc_ids into the vector */
  CommonTableReader();

  /** Push doc_ids directly into a caller-supplied ib_vector
  @param dest  destination vector to append doc_ids to */
  explicit CommonTableReader(ib_vector_t *dest);

  ~CommonTableReader();

  /** @return number of doc_ids collected so far */
  ulint size() const { return ib_vector_size(m_doc_ids); }

  /** @param n  element index
  @return the n'th collected doc_id */
  doc_id_t get(ulint n) const
  { return *static_cast<const doc_id_t*>(ib_vector_get_const(m_doc_ids, n)); }

  /** Discard collected doc_ids so the reader can be reused. */
  void clear() { ib_vector_reset(m_doc_ids); }

  /** Fast common table field extraction for known table format.
  Structure: (doc_id BIGINT UNSIGNED) - always known schema
  @param rec          record to extract from
  @param index        common table index
  @param doc_id       output doc_id value
  @return true if extraction successful */
  static bool extract_common_fields(
    const rec_t *rec, const dict_index_t *index,
    doc_id_t *doc_id);
};

/** Callback class for reading FTS config table records */
class ConfigReader : public RecordCallback
{
public:
  span<const char> value_span;
  ConfigReader();

  /** Extract the config table record.
  Structure: (key VARCHAR, db_trx_id, db_roll_ptr, value TEXT)
  @param rec          record to extract from
  @param index        config table index
  @param key_data     output pointer to key data
  @param key_len      output key length
  @param value_data   output pointer to value data (optional)
  @param value_len    output value length (optional)
  @return true if extraction successful */
  static bool extract_config_fields(
    const rec_t *rec, const dict_index_t *index,
    const byte **key_data, ulint *key_len,
    const byte **value_data = nullptr, ulint *value_len = nullptr);

  /** Direct config key comparison - compares first field with tuple value.
  @param search_tuple   search tuple containing target key
  @param rec           record to compare
  @param index         config table index
  @return comparison action */
  static RecordCompareAction compare_config_key(
    const dtuple_t *search_tuple, const rec_t *rec,
    const dict_index_t *index, const rec_offs *offsets);
};

/** Type alias for FTS record processor function */
using FTSRecordProcessor= std::function<
  dberr_t(const rec_t*, const dict_index_t*, const rec_offs*, void*)>;

/** Comparison modes for AuxRecordReader */
enum class AuxCompareMode
{
  /** >= comparison (range scan from word) */
  GREATER_EQUAL,
  /** > comparison (exclude exact match) */
  GREATER,
  /** LIKE pattern matching (prefix match) */
  LIKE,
  /** = comparison (exact match) */
  EQUAL
};

/** Callback class for reading FTS auxiliary index table records */
class AuxRecordReader : public RecordCallback
{
private:
  void *user_arg;
  ulint *total_memory;
  AuxCompareMode compare_mode;
  /* Optional shared heap. When it is allocated, every fts_word_t
  allocated via default_word_processor stores its text, heap_alloc,
  nodes vector in this words heap instead of private mem_heap_t
  per word. It is used for information schema read query */
  mem_heap_t* m_words_heap= nullptr;

private:
  /** FTS-specific record comparison logic */
  RecordCompareAction compare_record(
    const dtuple_t *search_tuple, const rec_t *rec,
    const dict_index_t *index, const rec_offs *offsets) noexcept;

  RecordComparator make_comparator()
  {
    return [this](const dtuple_t* search_tuple, const rec_t* rec,
                  const dict_index_t* index, const rec_offs* offsets)
           -> RecordCompareAction
    {
      return this->compare_record(search_tuple, rec, index, offsets);
    };
  }

public:
  /** Default word processor for FTS auxiliary table records */
  dberr_t default_word_processor(const rec_t *rec, const dict_index_t *index,
                                const rec_offs *offsets, void *user_arg);

  /* Constructor with custom processor */
  template<typename ProcessorFunc>
  AuxRecordReader(void* user_data,
                  ProcessorFunc proc_func,
                  AuxCompareMode mode= AuxCompareMode::GREATER_EQUAL)
    : RecordCallback(
        [this, proc_func](const rec_t* rec, const dict_index_t* index,
                          const rec_offs* offsets) -> dberr_t
 {
          return proc_func(rec, index, offsets, this->user_arg);
        },
 make_comparator()
      ),
      user_arg(user_data), total_memory(nullptr),
      compare_mode(mode) {}

  /* Different constructor with default word processing */
  AuxRecordReader(void *user_data, ulint *memory_counter,
                  AuxCompareMode mode= AuxCompareMode::GREATER_EQUAL)
    : RecordCallback(
        [this](const rec_t *rec, const dict_index_t* index,
               const rec_offs *offsets) -> dberr_t
        {
          return this->default_word_processor(rec, index, offsets,
                                              this->user_arg);
        },
 make_comparator()
      ),
      user_arg(user_data), total_memory(memory_counter),
      compare_mode(mode) {}

  /** Reset total memory counter */
  void reset_total_memory() { if (total_memory) *total_memory = 0; }

  void set_words_heap(mem_heap_t *words_heap) noexcept
  { m_words_heap= words_heap; }

  mem_heap_t *words_heap() const noexcept { return m_words_heap; }
};