Skip to content

Latest commit

 

History

History
220 lines (156 loc) · 5.19 KB

helper.rst

File metadata and controls

220 lines (156 loc) · 5.19 KB

Helper API

Helper wraps common statements that are awkward as fluent builders.

<?php

use Foolz\SphinxQL\Helper;

$helper = new Helper($conn);
$rows = $helper->showVariables()->execute()->getStored();

Core Patterns

Every helper method returns a SphinxQL instance, so you can:

  • inspect SQL with compile()->getCompiled()
  • run immediately with execute()
  • enqueue into a batch with enqueue()

Example:

$sql = $helper->showTables('rt')->compile()->getCompiled();
// SHOW TABLES LIKE 'rt'

SHOW Commands

Frequently used:

$helper->showMeta();
$helper->showWarnings();
$helper->showStatus();
$helper->showVariables();
$helper->showTables();
$helper->showCreateTable('rt');

Table introspection:

$helper->showTableStatus();
$helper->showTableStatus('rt');
$helper->showTableSettings('rt');
$helper->showTableIndexes('rt');

Compile outputs from tests:

  • showMeta() -> SHOW META
  • showWarnings() -> SHOW WARNINGS
  • showStatus() -> SHOW STATUS
  • showTableStatus() -> SHOW TABLE STATUS
  • showTableStatus('rt') -> SHOW TABLE rt STATUS
  • showTableSettings('rt') -> SHOW TABLE rt SETTINGS
  • showTableIndexes('rt') -> SHOW TABLE rt INDEXES

Maintenance and Runtime Commands

$helper->attachIndex('disk', 'rt');
$helper->flushRtIndex('rt');
$helper->truncateRtIndex('rt');
$helper->optimizeIndex('rt');
$helper->showIndexStatus('rt');
$helper->flushRamchunk('rt');
$helper->flushAttributes();
$helper->flushHostnames();
$helper->flushLogs();
$helper->reloadPlugins();
$helper->kill(123);

Selected compiled SQL from tests:

  • attachIndex('disk', 'rt') -> ATTACH INDEX disk TO RTINDEX rt
  • flushRtIndex('rt') -> FLUSH RTINDEX rt
  • optimizeIndex('rt') -> OPTIMIZE INDEX rt
  • showIndexStatus('rt') -> SHOW INDEX rt STATUS
  • flushRamchunk('rt') -> FLUSH RAMCHUNK rt
  • kill(123) -> KILL 123

CALL Helpers

CALL SNIPPETS:

$snippets = $helper->callSnippets(
    'this is my document text',
    'rt',
    'is',
    ['before_match' => '<em>', 'after_match' => '</em>']
)->execute()->getStored();

CALL KEYWORDS:

$keywords = $helper->callKeywords('test case', 'rt', 1)
    ->execute()
    ->getStored();

Suggest-family methods:

  • callSuggest($text, $index, $options = [])
  • callQSuggest($text, $index, $options = [])
  • callAutocomplete($text, $index, $options = [])

Compiled outputs from tests:

$helper->callSuggest('teh', 'rt', [
    'limit' => 5,
    'result_stats' => true,
    'search_mode' => 'WORDS',
])->compile()->getCompiled();

// CALL SUGGEST('teh', 'rt', 5 AS limit, 1 AS result_stats, 'words' AS search_mode)
$helper->callQSuggest('teh', 'rt', [
    'limit' => 3,
    'result_line' => false,
])->compile()->getCompiled();

// CALL QSUGGEST('teh', 'rt', 3 AS limit, 0 AS result_line)
$helper->callAutocomplete('te', 'rt', [
    'fuzzy' => 1,
    'append' => true,
    'preserve' => false,
])->compile()->getCompiled();

// CALL AUTOCOMPLETE('te', 'rt', 1 AS fuzzy, 1 AS append, 0 AS preserve)

Suggest Option Schemas

callSuggest() and callQSuggest() allowed options:

  • limit (int >= 0)
  • max_edits (int >= 0)
  • result_stats (bool)
  • delta_len (int >= 0)
  • max_matches (int >= 0)
  • reject (bool)
  • result_line (bool)
  • non_char (bool)
  • sentence (bool)
  • force_bigrams (bool)
  • search_mode (phrase or words)

callAutocomplete() allowed options:

  • layouts (string)
  • fuzzy (int 0..2)
  • fuzziness (int 0..2)
  • prepend (bool)
  • append (bool)
  • preserve (bool)
  • expansion_len (int >= 0)
  • force_bigrams (bool)

Capability-Aware Usage

Use capability checks before engine-dependent calls.

$caps = $helper->getCapabilities();

if ($helper->supports('call_autocomplete')) {
    $rows = $helper->callAutocomplete('te', 'rt', ['fuzzy' => 1])
        ->execute()
        ->getStored();
}

// throws UnsupportedFeatureException when unavailable
$helper->requireSupport('call_qsuggest', 'search suggestions');

getCapabilities() reports:

  • engine (MANTICORE, SPHINX2, SPHINX3, UNKNOWN)
  • version string
  • feature map

Pairs Utility

Convert key-value rows from SHOW commands into associative arrays.

$pairs = Helper::pairsToAssoc($helper->showVariables()->execute()->getStored());
$autocommit = (int) ($pairs['autocommit'] ?? 1);

Validation Behavior

Helper methods validate required identifiers and option shapes. Examples that throw SphinxQLException:

  • empty/invalid index names
  • unknown suggest option keys
  • invalid option types/ranges
  • non-positive kill() query ID