Справочник по профилям запросов Lance

В этом справочнике описаны метрики профиля для обычного сканирования Lance, векторного и полнотекстового поиска, а также получения строк по row ID на втором этапе. О сборе и просмотре профилей, а также об общем анализе операторов см. Руководство по анализу профиля запроса. Настройте доступ к Lance с помощью Lance Catalog.

примечание

Lance Catalog находится на экспериментальной стадии и поддерживается начиная с Apache Doris 4.2. Приведённые ниже метрики зависят от используемых версий FE/BE и поставляемой вместе с Doris версии Lance.

Перед выполнением запроса к Lance включите профилирование запросов:

SET enable_profile = true;

Ниже приведены имена, используемые в текущей реализации сбора метрик Lance.

Метаданные и планирование на FE

Для запросов через Catalog, включая обычное сканирование, COUNT, векторный и полнотекстовый поиск, изучите Lance Metadata Metrics в разделе Execution Summary:

Таймер	Описание
MetadataReadTime	Общее время чтения метаданных Catalog, включая определение параметров доступа к таблице, доступ к Dataset и освобождение ресурсов.
TableAccessResolveTime	Определение параметров доступа к таблице, включая доступ к Namespace, учётные данные и параметры хранилища.
DatasetOpenTime	Открытие Dataset на FE. Для запросов к историческим данным может потребоваться несколько открытий.
VersionResolveTime	Определение запрошенного исторического снимка, если это необходимо.
SchemaReadTime	Чтение схемы Arrow.
FragmentMetadataReadTime	Чтение метаданных Fragment и создание дескрипторов количества строк.
FieldIdsReadTime	Чтение и сопоставление ID полей Lance.
IndexMetadataReadTime	Обнаружение логических индексов и чтение метаданных сегментов индексов.
SplitPlanningTime	Планирование частей сканирования (split) для обычного сканирования, подсчёта по метаданным, векторного или полнотекстового поиска.

Для каждой выполненной операции или шага также предусмотрен соответствующий счётчик Calls, например DatasetOpenCalls. MetadataReadFailures и SplitPlanningFailures подсчитывают операции, завершившиеся ошибкой; время таких операций также учитывается. Это не количество SQL-операторов, завершившихся ошибкой. Для невыполненных шагов работы с метаданными счётчики не создаются. В этой группе суммируется работа с Catalog по всем таблицам и повторным чтениям в рамках SQL-оператора; отдельные файловые TVF и SHOW INDEX её не заполняют.

MetadataReadTime включает вложенные шаги работы с метаданными. SplitPlanningTime измеряется отдельно. Общие таймеры External Table Get Table Meta Time, External Table Get File Scan Tasks Time и External Table Meta Time включают соответствующую работу, поэтому не прибавляйте их повторно к детальным таймерам Lance или к охватывающему их времени анализа/планирования. DatasetOpenTime на FE и LanceDatasetOpenTime на BE относятся к разным процессам.

Группы на BE и границы сбора статистики

В профиле сканирования найдите TableReader → LanceReader. Названия групп служат метками, а не таймерами; их иерархия не означает, что время дочерних элементов можно складывать.

Группа	Содержимое
LanceTiming	Открытие Dataset, настройка Scanner и чтение через него, преобразование Runtime Filter, конвертация Arrow и получение строк по row ID.
LanceIO	Операции чтения в потоке выполнения, для которых собираются метрики, а также запросы и байты.
LanceIndex	Загрузка объектов и компонентов индексов, обращения к кэшу, сравнения, открытие индексов и поиск по партициям.
LanceVectorIndex	Выбор партиций IVF, дельты векторного индекса, этапы ANN и вычисление расстояний между векторами.
LanceScalarIndex	Вычисление выражений скалярного индекса, поиск по сегментам, кандидаты, резервные пути выполнения и сериализация результатов.
LanceExecutionPlan	Сортировка, слияние и операции Take в плане выполнения Lance.
LanceScan	Сканирование Fragment, диапазонов и строк, ожидание задач сканирования и построение Prefilter по row ID.
LanceSearchPlan	Количество сегментов поиска и Fragment, назначенных модулю чтения.
LanceDataCache	Кэш файлов данных и объём запросов к исходному хранилищу в байтах для дескриптора Dataset.

Таймеры Doris обновляются на границах измеряемых вызовов. Счётчики выполнения Lance накапливаются по данным callback статистики после достижения потоками EOF. Сбой, отмена или досрочное завершение могут привести к неполной статистике выполнения. Метрики Scanner регистрируются заранее, включая необязательные нативные метрики: нулевое значение может означать, что нативный путь выполнения не передал эту метрику. Само по себе отсутствие метрики или её нулевое значение не доказывает, что индекс, фильтр или путь I/O не использовался. COUNT, выполняемый только по метаданным, и получение строк по row ID не используют обычный путь callback Scanner.

Время суммируется по вызовам и параллельным задачам и может превышать фактическую длительность выполнения SQL-запроса. Анализируйте самый медленный Scanner с учётом планирования выполнения, ожидания зависимостей, обработки результатов на FE и задержки на клиенте. Не складывайте время всех Scanner или вложенных таймеров, чтобы восстановить длительность выполнения запроса.

Время работы модуля чтения

Таймер	Описание
LanceDatasetOpenTime	Открытие Dataset через общую Session на BE, включая необходимый доступ к метаданным. Повторное использование уже открытого в модуле чтения Dataset не учитывается как ещё одно открытие.
LanceScannerConfigureTime	Настройка Scanner, проекции, фильтров, callback и параметров split/поиска. Работа, отложенная до чтения, измеряется позднее.
LanceRuntimeFilterSqlTranslationTime	Преобразование и объединение фильтров Runtime Filter из Doris в Lance SQL, включая обращение к кэшу преобразований. Это не время выполнения фильтра.
LanceScannerNextTime	Суммарное время вызовов чтения пакетов, включая начальную подготовку, вычисления индекса, I/O, декодирование и ожидание. Не включает последующее преобразование Arrow в Doris.
LanceArrowToDorisBlockTime	Преобразование возвращённых пакетов Arrow в Doris Blocks как при сканировании, так и при получении строк по row ID.

LanceScannerNextTime пересекается с приведёнными ниже внутренними таймерами индексов, сканирования и плана выполнения. Большое значение само по себе не указывает на то, что узким местом является хранилище.

I/O, загрузка индексов и обращения к кэшу

Счётчик	Описание
LanceIOReadOps	Количество операций чтения, для которых собираются метрики. Это не число операций в секунду и не количество HTTP-запросов.
LanceIOReadRequests	Количество запросов на чтение из хранилища, для которых собираются метрики. Объединение или разбиение диапазонов может приводить к отличию от LanceIOReadOps.
LanceIOReadBytes	Объём прочитанных данных в байтах, сообщаемый планом выполнения, включая пути чтения данных и индексов, для которых собираются метрики. Может включать чтения из кэша; это не измеренный трафик к удалённому хранилищу и не размер декодированных данных в памяти.
LanceIndexObjectLoads	Количество загруженных объектов индексов верхнего уровня. Это не количество сегментов и не число загрузок их внутренних страниц.
LanceIndexComponentsLoaded	Количество загруженных внутренних компонентов индексов, например страниц, партиций или инвертированных списков (postings). Это не счётчик промахов кэша индексов; особенности загрузки, слияния и сбора метрик могут приводить к разным значениям.
LanceIndexCacheHits, LanceIndexCacheMisses	Обращения к кэшу в рамках этого выполнения, о которых сообщают пути работы с индексами со сбором метрик. Они отличаются от суммарных значений попаданий и промахов Session для всего BE. Некоторые потоковые пути не сохраняют загруженное содержимое, поэтому одни лишь постоянные промахи не доказывают, что ёмкости кэша недостаточно.
LanceIndexComparisons	Объём сравнений и поисковых операций, определяемый реализацией каждого индекса. Это не число строк-кандидатов и не единая единица затрат CPU для разных типов индексов.

Эти счётчики относятся к путям работы с векторными, скалярными и полнотекстовыми индексами, для которых собираются метрики. Объект индекса может оставаться в кэше, тогда как его страницы или партиции требуют загрузки. Прежде чем увеличивать ёмкость, совместно проанализируйте использование кэша, повторяемые нагрузки с холодным и прогретым кэшем, а также I/O. Об отдельном дисковом кэше данных и метриках для всего BE см. Проверка эффективности кэша.

Row-ID Prefilter и работа скалярного индекса

Метрики Row-ID Prefilter описывают работу загрузчика, который получает row ID и строит маску допустимых строк. Они не измеряют каждый filter в TVF, каждое обращение к скалярному индексу или итоговое число результатов ANN/FTS.

Счётчик или таймер	Описание
RowIdPrefilterLoads	Количество фактических запусков загрузчика row ID. Повторяющиеся узлы запроса могут выполнять загрузку повторно.
RowIdPrefilterInputRows, RowIdPrefilterInputBatches	Количество входных row ID со значением, отличным от NULL, и пакетов, обработанных загрузчиком.
RowIdPrefilterIds	Допустимые row ID, сохранённые в построенной маске; значения суммируются по загрузчикам без удаления дубликатов в масштабе запроса.
RowIdPrefilterLoadTime	Общее время работы загрузчика, включая опрос входного потока и построение маски.
RowIdPrefilterInputTime, RowIdPrefilterBuildTime	Время ожидания/чтения входного потока и время построения маски. Оба входят в RowIdPrefilterLoadTime; не складывайте общее время с его составляющими.
LanceScalarIndexQueryTime	Вычисление выражения скалярного индекса, которое может включать несколько поисков по индексам и операций над множествами.
LanceScalarIndexResultSerializationTime	Сериализация результатов скалярного индекса для последующих узлов Lance; это не сетевая сериализация и не преобразование Arrow в Doris.
LanceScalarIndexSegmentsRequested, LanceScalarIndexSegmentsSearched	Количество запросов к пути выполнения с явно заданным сегментом скалярного индекса и количество завершённых вычислений по сегментам. Это число выполнений, а не число уникальных сегментов таблицы.
LanceScalarIndexSegmentFallbacks	Количество переходов с ускоренного пути с явно заданным сегментом скалярного индекса на сканирование с применением полного фильтра в пределах назначенного набора Fragment. Резервный путь может использоваться и для сегмента, по которому выполнялся поиск.
LanceScalarIndexCandidateRows	Размер маски кандидатов, если он известен, до применения модулем чтения ограничений по Fragment и полного предиката. Это не число результатов SQL-запроса; ноль также может означать, что кардинальность неизвестна.
LanceScalarIndexCandidateEvaluationTime	Подготовка, вычисление и установка кандидатов для сегмента скалярного индекса, включая открытие индекса, поиск и подготовку резервного пути. Не включает последующее сканирование данных.
LanceScalarIndexSegmentSearchTime	Вычисление индексного выражения выбранного сегмента, включая загрузку индекса и операции над множествами. Входит в LanceScalarIndexCandidateEvaluationTime.

Один сегмент может охватывать больше Fragment, чем читает одна задача, а повторные задачи могут снова учитывать тех же кандидатов. Не трактуйте CandidateRows как число совпадений в пределах отдельной задачи. Для обычного пути вычисления скалярных выражений и пути с явно заданным сегментом используются разные таймеры; их значения могут различаться. Большие маски и повторное вычисление по сегментам могут расходовать CPU и память даже при прогретом кэше.

Работа с векторами и планом выполнения

Счётчик или таймер	Описание
LanceIVFPartitionsConsidered	Общее число партиций IVF, из которых выполняется выбор, суммированное по выбранным дельтам индекса. Это не число выполненных проб (probes).
LanceIVFPartitionSelectionTime	Выбор партиций IVF для запроса. Не включает открытие индекса, в рамках которого выполняется этот выбор.
LanceIndexPartitionsSearched	Поиски по партициям, о которых фактически сообщает выполнение индекса. FTS также сообщает эту метрику; интерпретируйте её с учётом LanceSearchType. Это не количество уникальных партиций в рамках всего запроса.
LanceVectorIndexDeltasSearched	Дельты векторного индекса, переданные в путь выполнения ANN по партициям. Это не доказывает, что поиск завершился для каждой дельты.
LanceIndexOpenTime	Открытие дескриптора индекса, включая обращение к кэшу и доступ к метаданным.
LanceIndexPartitionLoadTime, LanceIndexPartitionPrepareTime	Загрузка партиции включает обращение к кэшу, ожидание заполнения кэша и загрузку/декодирование при промахе. Подготовка партиции включает загрузку и подготовку фильтра; эти таймеры пересекаются.
LanceIndexPrefilterWaitTime	Ожидание готовности Prefilter индекса. Это отдельная операция, отличная от построения маски row ID.
LanceIndexCpuQueueWaitTime	Ожидание между передачей задачи поиска по партиции на выполнение и началом её работы на CPU.
LanceIndexSearchTime	Поиск в подготовленной партиции на CPU, включая подготовку запроса и формирование результата.
LanceIndexQueryPrepareTime	Создание калькулятора расстояний и таблиц поиска для запроса.
LanceIndexDistanceTopKTime	Совмещённая фильтрация кандидатов, вычисление расстояний и обновление кучи Top-K. Этот таймер не измеряет исключительно вычисление расстояний или уточнение результатов.
LanceIndexResultMaterializeTime	Преобразование кучи результатов поиска в массивы/пакеты Arrow. Это не получение выходных данных на втором этапе в Doris.
LanceANNPartitionExecTime, LanceANNSubIndexExecTime, LanceANNBatchExecTime	Время вычислений узлов выполнения ANN, для которых собираются метрики. Может пересекаться с детальными таймерами индекса.
LanceVectorDistanceComputeTime	Время вычислений, сообщаемое узлом выполнения, который рассчитывает расстояния между векторами; не охватывает все расчёты расстояний при использовании индекса.
LanceSortComputeTime, LanceSortMergeComputeTime, LanceTakeExecTime	Время сортировки, слияния и операций Take в узлах выполнения Lance. Это не время Doris TopN и не полное время получения данных на втором этапе.

Работа с партициями выполняется параллельно, а таймеры могут быть вложенными или пересекаться. Не складывайте LanceIndexSearchTime с входящими в него временами подготовки запроса, вычисления расстояний/Top-K и формирования результатов. Прежде чем менять nprobes, ef или refine_factor, сопоставьте число проб, ожидание в очереди CPU, ожидание Prefilter и I/O; измеряйте и полноту поиска (recall), и задержку.

Запланированная работа, просканированные строки и получение выходных данных

Счётчик или таймер	Описание
LancePlannedIndexSegmentCount	Количество сегментов поискового индекса, назначенных модулю чтения; накапливается при настройке split. Не подтверждает завершение поиска.
LancePlannedIndexedFragmentCount	Fragment, назначенные split для векторного/полнотекстового поиска по индексу.
LancePlannedFlatSearchFragmentCount	Fragment, назначенные split для векторного Flat Search. FTS не регистрирует этот счётчик.
LanceFragmentsScanned, LanceRowOffsetRangesScanned, LanceRowsScanned	Fragment, диапазоны смещений строк и строки, о которых сообщает путь выполнения FilteredRead. Не все пути чтения заполняют эти счётчики; это не количество уникальных элементов во всей таблице и не число строк в итоговом результате SQL-запроса.
LanceScanTaskWaitTime	Время ожидания задач чтения потребителем FilteredRead. Это не время планирования Scanner в Doris и не полное суммарное время ожидания I/O.
LanceRowIdFetchCalls, LanceRowIdFetchRows	Вызовы take_rows на втором этапе и количество полученных строк.
LanceRowIdTakeReadTime	Создание и чтение потока Take по row ID, включая отложенные чтения; не включает преобразование Arrow в Doris.
LanceRowIdFetchTotalTime	Общее время получения строк по непустому набору row ID, включая открытие Dataset, чтение через Take, преобразование и проверки результата. Включает перечисленные выше этапы и не учитывает накладные расходы полного цикла RPC/Materialization.

Для анализа планирования поиска сравните поля EXPLAIN lanceSearchIndexSegments, lanceSearchIndexFragments и lanceSearchUnindexedFragments со счётчиками LanceSearchPlan. Для обычного сканирования с использованием сегментов скалярного индекса используйте lanceGroupingIndexSegments, lanceGroupingIndexedFragments и lanceGroupingUnindexedFragments; это поля плана FE, а не счётчики профиля BE. Количество Fragment суммируется по задачам, при этом дубликаты могут сохраняться.

Двухэтапное получение строк использует отдельный модуль чтения и не регистрирует callback статистики выполнения Scanner. Его таймеры и счётчики получения строк, а также LanceDataCacheBytesReadFromCache/LanceDataCacheBytesReadFromRemote также приводятся в информации профиля получения строк по ID / материализации (Row ID Fetch/Materialization). Отсутствие там LanceIOReadBytes не означает, что I/O не выполнялся. Рассматривайте сканирование и получение строк раздельно и не учитывайте одну и ту же экспортированную статистику получения строк дважды.

Используйте LanceDatasetVersion и LanceDatasetUri, чтобы определить снимок, на котором выполнялся запрос, а LanceSearchType, чтобы различать векторный и полнотекстовый поиск. LanceTopK, LanceOffset, LanceFtsCoverageMode, LanceFtsQueryType, LanceFtsMatchOperator, LanceFtsMaxFuzzyDistance, LanceFtsPhraseSlop, LancePushdownFormat и записи с ID Runtime Filter описывают конфигурацию или состояние pushdown. Это информационные строки, а не суммируемые счётчики. LanceTopK и LanceOffset описывают запрос для каждого split: для TVF-запроса с top_k=K и offset=n поисковые split запрашивают до K+n кандидатов с локальным смещением 0; итоговый Doris TopN применяет смещение, заданное пользователем.