### Running Sonic Server: Command Line and Docker

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Examples for starting the Sonic server using command-line arguments, environment variables, and Docker. This includes specifying configuration files, ports, and volumes for persistent storage.

```bash
# Start Sonic with configuration file
./sonic -c /path/to/config.cfg

```

```bash
# Start Sonic with environment variable for password
SECRET=mypassword ./sonic -c /path/to/config.cfg

```

```bash
# Docker deployment example
docker pull valeriansaliou/sonic:v1.4.9
docker run -p 1491:1491 \
  -v /path/to/config.cfg:/etc/sonic.cfg \
  -v /path/to/store/:/var/lib/sonic/store/ \
  valeriansaliou/sonic:v1.4.9

```

```bash
# Build from source (requires Rust toolchain)
cargo build --release
./target/release/sonic -c config.cfg

```

```bash
# Install from Cargo
cargo install sonic-server
sonic -c /path/to/config.cfg

```

--------------------------------

### Sonic Channel Search Flow Example (Telnet)

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

An example demonstrating the Sonic Channel Search mode interaction using telnet. This flow shows the sequence of commands and responses for querying, suggesting, and basic server interaction.

```bash
T1: telnet sonic.local 1491
T2: Trying ::1...
T3: Connected to sonic.local.
T4: Escape character is '^]'.
T5: CONNECTED <sonic-server v1.0.0>
T6: START search SecretPassword
T7: STARTED search protocol(1) buffer(20000)
T8: QUERY messages user:0dcde3a6 "valerian saliou" LIMIT(10)
T9: PENDING Bt2m2gYa
T10: EVENT QUERY Bt2m2gYa conversation:71f3d63b conversation:6501e83a
T11: QUERY helpdesk user:0dcde3a6 "gdpr" LIMIT(50)
T12: PENDING y57KaB2d
T13: QUERY helpdesk user:0dcde3a6 "law" LIMIT(50) OFFSET(200)
T14: PENDING CjPvE5t9
T15: PING
T16: PONG
T17: EVENT QUERY CjPvE5t9
T18: EVENT QUERY y57KaB2d article:28d79959
T19: SUGGEST messages user:0dcde3a6 "val"
T20: PENDING z98uDE0f
T21: EVENT SUGGEST z98uDE0f valerian valala
T22: QUIT
T23: ENDED quit
T24: Connection closed by foreign host.
```

--------------------------------

### Sonic PUSH Command Examples (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Demonstrates adding data to the Sonic index using the PUSH command. Includes examples for basic text insertion, handling escaped quotes, specifying language for processing, and disabling language detection.

```bash
# Basic push command
PUSH messages user:0dcde3a6 conversation:71f3d63b "Hello Valerian Saliou, how are you today?"
OK

# Push with escaped quotes in text
PUSH articles default article:123 "The \"quick brown\" fox jumps"
OK

# Push with explicit language
PUSH products default product:abc123 "Machine learning algorithm" LANG(eng)
OK

# Push with language detection disabled
PUSH catalog default item:sku789 "ABC-123-XYZ" LANG(none)
OK

```

--------------------------------

### Sonic Channel Control Mode Telnet Example

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

An example demonstrating how to connect to the Sonic server in control mode using telnet and execute administrative commands. It shows the connection process, authentication, triggering a consolidation, pinging the server, and disconnecting.

```bash
telnet sonic.local 1491
START control SecretPassword
TRIGGER consolidate
PING
QUIT
```

--------------------------------

### Start Sonic with Cargo

Source: https://github.com/valeriansaliou/sonic/blob/master/CONTRIBUTING.md

Runs the Sonic application using Cargo. Execute this command from the repository root to start the Sonic executable. This is useful for local development and testing the application's functionality.

```shell
cargo run
```

--------------------------------

### Sonic Channel - START Command

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

Initiates a Sonic Channel session by selecting a mode and providing an optional password. The response includes a buffer size for subsequent commands.

```APIDOC
## START Command

### Description
Selects the mode for the connection (search or ingest) and provides authentication if configured. The server responds with a buffer size to manage command lengths.

### Method
This is a conceptual command within the Sonic Channel protocol, not a standard HTTP method.

### Endpoint
This is a conceptual endpoint within the Sonic Channel protocol, not a standard HTTP endpoint.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**mode** (string) - Required - The mode to use for the connection. Accepted values are `search` or `ingest`.
**password** (string) - Optional - The password for authentication, as specified in the `config.cfg` file.

### Request Example
```
START search mysecretpassword
```

### Response
#### Success Response (STARTED)
- **buffer_size** (integer) - The size of the buffer in bytes to manage command lengths.

#### Response Example
```
STARTED 20000
```

#### Error Response (ENDED)
- **error_message** (string) - Description of the error.

#### Response Example
```
ENDED not_recognized
```
```

--------------------------------

### Sonic Ingest Mode Telnet Example

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

An example demonstrating the use of Sonic's Ingest mode via telnet. This flow illustrates connecting to the server, authenticating, performing PUSH, COUNT, FLUSHO, FLUSHB, PING, and QUIT operations, and handling potential error responses.

```bash
T1: telnet sonic.local 1491
T2: Trying ::1...
T3: Connected to sonic.local.
T4: Escape character is '^]'.
T5: CONNECTED <sonic-server v1.0.0>
T6: START ingest SecretPassword
T7: STARTED ingest protocol(1) buffer(20000)
T8: PUSH messages user:0dcde3a6 conversation:71f3d63b Hey Valerian
T9: ERR invalid_format(PUSH <collection> <bucket> <object> "<text>")
T10: PUSH messages user:0dcde3a6 conversation:71f3d63b "Hello Valerian Saliou, how are you today?"
T11: OK
T12: COUNT messages user:0dcde3a6
T13: RESULT 43
T14: COUNT messages user:0dcde3a6 conversation:71f3d63b
T15: RESULT 1
T16: FLUSHO messages user:0dcde3a6 conversation:71f3d63b
T17: RESULT 1
T18: FLUSHB messages user:0dcde3a6
T19: RESULT 42
T20: PING
T21: PONG
T22: QUIT
T23: ENDED quit
T24: Connection closed by foreign host.
```

--------------------------------

### START control - Initiate Control Session

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Connect to the Sonic Channel in control mode to perform administrative operations.

```APIDOC
## Starting a Control Session

### Description
Connect to Sonic Channel in control mode to perform administrative operations like triggering consolidation, backups, and retrieving server information.

### Method
START control

### Endpoint
(Not applicable, typically via telnet or similar)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Connect and start control mode
telnet localhost 1491
START control SecretPassword
```

### Response
#### Success Response (STARTED)
- **mode** (string) - 'control'
- **protocol_version** (integer) - The protocol version.
- **buffer_size** (integer) - The buffer size for the session.

#### Response Example
```
CONNECTED <sonic-server v1.4.9>
STARTED control protocol(1) buffer(20000)
```
```

--------------------------------

### Sonic SUGGEST Command Examples (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Illustrates how to use the SUGGEST command in Sonic for auto-completion. It provides word suggestions based on partial input, with options to set custom result limits for faster responses.

```bash
# Basic suggest for auto-completion
SUGGEST messages user:0dcde3a6 "val"
PENDING z98uDE0f
EVENT SUGGEST z98uDE0f valerian valala valencia

# Suggest with custom limit
SUGGEST products default "mach" LIMIT(10)
PENDING a45TyU2k
EVENT SUGGEST a45TyU2k machine machinery machining machines

# Suggest with minimum limit (fast response)
SUGGEST articles default "pr" LIMIT(3)
PENDING b23KxV8m
EVENT SUGGEST b23KxV8m privacy product price

```

--------------------------------

### INFO - Get Server Information

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Retrieve server metadata including uptime, version, and operational statistics for monitoring and debugging purposes.

```APIDOC
## INFO - Get Server Information

### Description
Retrieve server metadata including uptime, version, and operational statistics for monitoring and debugging purposes.

### Method
INFO

### Endpoint
(Not applicable, command-line interface in control mode)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
INFO
```

### Response
#### Success Response (Server Metrics)
- **uptime** (integer) - Seconds since server start.
- **clients_connected** (integer) - Number of active connections.
- **commands_total** (integer) - Total commands processed.
- **command_latency_best** (integer) - Fastest command execution in microseconds.
- **command_latency_worst** (integer) - Slowest command execution in microseconds.

#### Response Example
```
uptime(3600) clients_connected(5) commands_total(12847) command_latency_best(15) command_latency_worst(2304)
```
```

--------------------------------

### Sonic LIST Command Examples (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Shows how to use the LIST command in Sonic to enumerate words within an index. Supports pagination via LIMIT and OFFSET, useful for administrative tasks or exploring indexed content.

```bash
# List first 100 words in index
LIST messages user:0dcde3a6 LIMIT(100)
PENDING c67LmN4p
EVENT LIST c67LmN4p abandoned about abstract account action active add address...

# List with offset for pagination
LIST products default LIMIT(50) OFFSET(150)
PENDING d89OpQ5r
EVENT LIST d89OpQ5r notebook nuclear number nutrition oak object ocean office...

# List maximum allowed words
LIST helpdesk default LIMIT(500)
PENDING e12RsT6u
EVENT LIST e12RsT6u faq feature feedback file filter...

```

--------------------------------

### Configuration File Setup (TOML)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Illustrates the structure for configuring the Sonic server using a TOML file. This configuration file governs various server behaviors, including network settings, authentication mechanisms, search query limits, and storage path directives.

```toml
# Configuration File Setup
# Configure Sonic server behavior including network settings, authentication, search limits, and storage paths through the TOML configuration file.

```

--------------------------------

### PUSH - Add Data to Index (Batch Normalization Example)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Adds long text or multiple pieces of data to the index for a given object. Useful for batch normalization examples or additive indexing where multiple attributes of an object are indexed separately. Supports adding text to default or specific buckets.

```bash
# Push long text (batch normalization example)
PUSH messages default conversation:1 "Batch normalization is a technique for improving the speed, performance, and stability of artificial neural networks"
OK
```

```bash
# Multiple pushes for same object (additive indexing)
PUSH contacts user:42 contact:999 "John Doe"
OK
PUSH contacts user:42 contact:999 "Software Engineer at Acme Corp"
OK
PUSH contacts user:42 contact:999 "john.doe@example.com"
OK
```

--------------------------------

### Sonic QUERY Command Examples (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Demonstrates various ways to query the Sonic index for object identifiers. Supports basic search, pagination with OFFSET, and explicit language filtering using ISO 639-3 codes or disabling language processing.

```bash
# Basic query syntax
QUERY messages user:0dcde3a6 "valerian saliou" LIMIT(10)
PENDING Bt2m2gYa
EVENT QUERY Bt2m2gYa conversation:71f3d63b conversation:6501e83a

# Query with offset for pagination
QUERY helpdesk default "privacy policy" LIMIT(20) OFFSET(40)
PENDING x9dKm3pL
EVENT QUERY x9dKm3pL article:28d79959 article:45a82bc1 article:91e3f7c2

# Query with explicit language code (ISO 639-3)
QUERY products default "machine learning" LANG(eng) LIMIT(50)
PENDING yH8nP2qR
EVENT QUERY yH8nP2qR product:abc123 product:def456 product:ghi789

# Query with no language processing (raw search)
QUERY catalog default "SKU-12345" LANG(none)
PENDING mP9kT4wX
EVENT QUERY mP9kT4wX item:sku-12345

```

--------------------------------

### Connect and Start Sonic Search Session (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Establishes a connection to the Sonic server via telnet on port 1491 and authenticates in search mode. This is the initial step before executing any search-related commands. Requires the Sonic server to be running.

```bash
# Using telnet to connect to Sonic
telnet localhost 1491

# Server responds with:
CONNECTED <sonic-server v1.4.9>

# Start search mode with password
START search SecretPassword

# Server responds with:
STARTED search protocol(1) buffer(20000)

# Now you can execute search commands

```

--------------------------------

### Run Sonic with Defined Environment Variable

Source: https://github.com/valeriansaliou/sonic/blob/master/CONFIGURATION.md

Shows how to execute the Sonic binary while providing a value for an environment variable used in the configuration. This example sets the `SECRET` environment variable to `secretphrase` before running Sonic with a specified configuration file.

```bash
SECRET=secretphrase ./sonic -c /path/to/config.cfg
```

--------------------------------

### Format Rust Code with Rustfmt

Source: https://github.com/valeriansaliou/sonic/blob/master/CONTRIBUTING.md

Formats Rust source files according to the project's style guidelines using the rustfmt utility. This command should be run before submitting code changes to ensure consistency.

```shell
rustfmt src/*.rs
```

--------------------------------

### Connect and Start Sonic Ingest Session (Bash)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Initiates a connection to the Sonic server on port 1491 and authenticates in ingest mode. This session is used for adding, removing, counting, and flushing data within the Sonic index.

```bash
# Connect and start ingest mode
telnet localhost 1491
CONNECTED <sonic-server v1.4.9>

START ingest SecretPassword
STARTED ingest protocol(1) buffer(20000)

# Now you can execute ingest commands

```

--------------------------------

### Run Integration Tests with Script

Source: https://github.com/valeriansaliou/sonic/blob/master/CONTRIBUTING.md

Executes integration tests for Sonic. Navigate to the specified directory within the repository root and run the provided script. These tests verify the behavior of the application as a whole.

```shell
./run.sh
```

--------------------------------

### Starting a Control Session

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Connects to the Sonic Channel in control mode to perform administrative operations. This mode allows for actions such as triggering consolidation, backups, and retrieving server information. Requires connecting via telnet and then initiating the control session with a password.

```bash
# Connect and start control mode
telnet localhost 1491
CONNECTED <sonic-server v1.4.9>

START control SecretPassword
STARTED control protocol(1) buffer(20000)

# Now you can execute control commands
```

--------------------------------

### Build Sonic with Cargo

Source: https://github.com/valeriansaliou/sonic/blob/master/CONTRIBUTING.md

Builds the Sonic project using the Cargo build system. This command should be run from the repository root. It compiles the Rust code, preparing the executable for running or further testing.

```shell
cargo build
```

--------------------------------

### INFO - Get Server Information

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Retrieves server metadata, including uptime, connected clients, total commands processed, and command latency statistics. This command is crucial for monitoring server health, performance, and debugging operational issues. It returns key-value pairs representing various server metrics.

```bash
# Get server information
INFO
uptime(3600) clients_connected(5) commands_total(12847) command_latency_best(15) command_latency_worst(2304)

# INFO returns key-value pairs with server metrics
# uptime: seconds since server start
# clients_connected: number of active connections
# commands_total: total commands processed
# command_latency_best: fastest command execution (microseconds)
# command_latency_worst: slowest command execution (microseconds)
```

--------------------------------

### Run Unit Tests with Cargo

Source: https://github.com/valeriansaliou/sonic/blob/master/CONTRIBUTING.md

Executes all unit tests for the Sonic project. Run this command from the repository root to ensure code correctness and identify regressions. It relies on Rust's built-in testing framework.

```shell
cargo test
```

--------------------------------

### Sonic Channel Control Mode Commands

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

This snippet lists the available commands for the Sonic Channel Control mode, including their syntax and time complexity. These commands are used for administrative tasks such as triggering actions, getting server information, and managing the connection.

```bash
TRIGGER [<action>]? [<data>]?
INFO
PING
HELP [<manual>]?
QUIT
```

--------------------------------

### Node.js Client Integration with Sonic

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Demonstrates integrating Sonic into Node.js applications using the 'sonic-channel' library for indexing documents, performing searches, getting auto-complete suggestions, counting items, and removing documents. It utilizes a Promise-based API.

```javascript
// npm install sonic-channel

const SonicChannelSearch = require("sonic-channel").Search;
const SonicChannelIngest = require("sonic-channel").Ingest;

// Initialize search client
const searchClient = new SonicChannelSearch({
  host: "localhost",
  port: 1491,
  auth: "SecretPassword"
});

// Initialize ingest client
const ingestClient = new SonicChannelIngest({
  host: "localhost",
  port: 1491,
  auth: "SecretPassword"
});

// Wait for connections
searchClient.connect({ connected: () => console.log("Search connected") });
ingestClient.connect({ connected: () => console.log("Ingest connected") });

// Push data to index
async function indexDocument() {
  await ingestClient.push(
    "messages",
    "user:42",
    "conversation:123",
    "Hello world, this is a test message"
  );
  console.log("Document indexed");
}

// Search for documents
async function searchDocuments() {
  const results = await searchClient.query(
    "messages",
    "user:42",
    "test message",
    { limit: 10 }
  );
  console.log("Search results:", results);
  // Output: ["conversation:123"]
}

// Auto-complete suggestions
async function getSuggestions() {
  const suggestions = await searchClient.suggest(
    "messages",
    "user:42",
    "tes",
    { limit: 5 }
  );
  console.log("Suggestions:", suggestions);
  // Output: ["test", "testing", "tesla"]
}

// Count indexed items
async function countItems() {
  const count = await ingestClient.count("messages", "user:42");
  console.log("Total indexed terms:", count);
}

// Flush object from index
async function removeDocument() {
  const removed = await ingestClient.flusho(
    "messages",
    "user:42",
    "conversation:123"
  );
  console.log("Objects flushed:", removed);
}

// Complete workflow example
async function completeWorkflow() {
  // Index multiple documents
  await ingestClient.push("products", "default", "prod:1",
    "Wireless Bluetooth Headphones with Noise Cancellation");
  await ingestClient.push("products", "default", "prod:2",
    "USB-C Charging Cable Fast Charge");
  await ingestClient.push("products", "default", "prod:3",
    "Wireless Mouse Ergonomic Design");

  // Search for products
  const results = await searchClient.query("products", "default", "wireless");
  console.log("Found products:", results);
  // Output: ["prod:1", "prod:3"]

  // Get suggestions
  const hints = await searchClient.suggest("products", "default", "wir");
  console.log("Suggestions:", hints);
  // Output: ["wireless"]
}

```

--------------------------------

### Sonic Channel Search Commands Documentation

Source: https://github.com/valeriansaliou/sonic/blob/master/PROTOCOL.md

This documentation outlines the commands available within the Sonic Channel's Search mode. It includes syntax, purpose, and time complexity for each command. Note that once in search mode, switching to other modes is not permitted.

```text
QUERY <collection> <bucket> "<terms>" [LIMIT(<count>)]? [OFFSET(<count>)]? [LANG(<locale>)]?
SUGGEST <collection> <bucket> "<word>" [LIMIT(<count>)]?
LIST <collection> <bucket> [LIMIT(<count>)]? [OFFSET(<count>)]?
PING
HELP [<manual>]?
QUIT
```

--------------------------------

### LIST - Enumerate Index Words

Source: https://context7.com/valeriansaliou/sonic/llms.txt

List all words in a bucket index with pagination support, useful for administrative tasks and understanding indexed content.

```APIDOC
## LIST - Enumerate Index Words

### Description
List all words in a bucket index with pagination support, useful for administrative tasks and understanding indexed content.

### Method
LIST [index:collection] [index:bucket] [OPTIONS]

### Endpoint
This is a command sent over the Sonic Channel after starting a search session.

### Parameters

#### Query Parameters
- **LIMIT** (integer) - Optional - The maximum number of words to list. Defaults to 100, max is 500.
- **OFFSET** (integer) - Optional - The number of words to skip for pagination.

### Request Example
```bash
# List first 100 words
LIST messages user:0dcde3a6 LIMIT(100)

# List with offset
LIST products default LIMIT(50) OFFSET(150)

# List maximum allowed words
LIST helpdesk default LIMIT(500)
```

### Response

#### Success Response (EVENT)
- **LIST** (string) - Indicates a list event.
- **[PENDING_ID]** (string) - A unique identifier for the pending operation.
- **[INDEXED_WORDS]** (string) - Comma-separated list of words in the index.

#### Response Example
```
PENDING c67LmN4p
EVENT LIST c67LmN4p abandoned about abstract account action active add address...
```
```

--------------------------------

### PUSH - Add Data to Index

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Push searchable text into the index with collection, bucket, and object identifiers, optionally specifying language for proper lexing and stop-word removal.

```APIDOC
## PUSH - Add Data to Index

### Description
Push searchable text into the index with collection, bucket, and object identifiers, optionally specifying language for proper lexing and stop-word removal.

### Method
PUSH [index:collection] [index:bucket] [object id] [searchable text] [OPTIONS]

### Endpoint
This is a command sent over the Sonic Channel after starting an ingest session.

### Parameters

#### Query Parameters
- **LANG** (string) - Optional - Specify the language code (e.g., 'eng') for processing or 'none' to disable language detection and processing.

### Request Example
```bash
# Basic push command
PUSH messages user:0dcde3a6 conversation:71f3d63b "Hello Valerian Saliou, how are you today?"

# Push with escaped quotes in text
PUSH articles default article:123 "The \"quick brown\" fox jumps"

# Push with explicit language
PUSH products default product:abc123 "Machine learning algorithm" LANG(eng)

# Push with language detection disabled
PUSH catalog default item:sku789 "ABC-123-XYZ" LANG(none)
```

### Response

#### Success Response (OK)
- **OK** (string) - Indicates the data was successfully pushed.

#### Response Example
```
OK
```
```

--------------------------------

### SUGGEST - Auto-complete Words

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Provide real-time word suggestions based on partial input, enabling instant search suggestions in user interfaces.

```APIDOC
## SUGGEST - Auto-complete Words

### Description
Provide real-time word suggestions based on partial input, enabling instant search suggestions in user interfaces with configurable result limits.

### Method
SUGGEST [index:collection] [index:bucket] [search term prefix] [OPTIONS]

### Endpoint
This is a command sent over the Sonic Channel after starting a search session.

### Parameters

#### Query Parameters
- **LIMIT** (integer) - Optional - The maximum number of suggestions to return.

### Request Example
```bash
# Basic suggest
SUGGEST messages user:0dcde3a6 "val" LIMIT(5)

# Suggest with custom limit
SUGGEST products default "mach" LIMIT(10)

# Suggest with minimum limit (fast response)
SUGGEST articles default "pr" LIMIT(3)
```

### Response

#### Success Response (EVENT)
- **SUGGEST** (string) - Indicates a suggest event.
- **[PENDING_ID]** (string) - A unique identifier for the pending operation.
- **[SUGGESTED_WORDS]** (string) - Comma-separated list of suggested words.

#### Response Example
```
PENDING z98uDE0f
EVENT SUGGEST z98uDE0f valerian valala valencia
```
```

--------------------------------

### PUSH - Indexing Data

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Ingest text data into the Sonic index for searchable objects.

```APIDOC
## PUSH - Indexing Data

### Description
Ingest text data into the Sonic index for searchable objects. This can be used for single messages or multiple pieces of text for the same object.

### Method
PUSH

### Endpoint
(Not applicable, command-line interface)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
PUSH messages default conversation:1 "Batch normalization is a technique for improving the speed, performance, and stability of artificial neural networks"
```

### Response
#### Success Response (OK)
- **status** (string) - Indicates successful indexing.

#### Response Example
```
OK
```

## PUSH - Additive Indexing

### Description
Allows for adding multiple text fields to the same object, enabling additive indexing for richer object representations.

### Method
PUSH

### Endpoint
(Not applicable, command-line interface)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
PUSH contacts user:42 contact:999 "John Doe"
PUSH contacts user:42 contact:999 "Software Engineer at Acme Corp"
PUSH contacts user:42 contact:999 "john.doe@example.com"
```

### Response
#### Success Response (OK)
- **status** (string) - Indicates successful indexing.

#### Response Example
```
OK
```
```

--------------------------------

### QUERY - Search the Index

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Execute full-text search queries against a collection and bucket, returning object identifiers that match the search terms.

```APIDOC
## QUERY - Search the Index

### Description
Execute full-text search queries against a collection and bucket, returning object identifiers that match the search terms with optional limits, offsets, and language specifications.

### Method
QUERY [index:collection] [index:bucket] [search terms] [OPTIONS]

### Endpoint
This is a command sent over the Sonic Channel after starting a search session.

### Parameters

#### Query Parameters
- **LIMIT** (integer) - Optional - The maximum number of results to return.
- **OFFSET** (integer) - Optional - The number of results to skip for pagination.
- **LANG** (string) - Optional - Explicitly set the language code (e.g., 'eng') or 'none' for raw search.

### Request Example
```bash
# Basic query
QUERY messages user:0dcde3a6 "valerian saliou" LIMIT(10)

# Query with offset
QUERY helpdesk default "privacy policy" LIMIT(20) OFFSET(40)

# Query with explicit language
QUERY products default "machine learning" LANG(eng) LIMIT(50)

# Query with no language processing
QUERY catalog default "SKU-12345" LANG(none)
```

### Response

#### Success Response (EVENT)
- **QUERY** (string) - Indicates a query event.
- **[PENDING_ID]** (string) - A unique identifier for the pending operation.
- **[RESULT_IDENTIFIERS]** (string) - Comma-separated list of matching object identifiers.

#### Response Example
```
PENDING Bt2m2gYa
EVENT QUERY Bt2m2gYa conversation:71f3d63b conversation:6501e83a
```
```

--------------------------------

### Sonic Server Configuration File (config.cfg)

Source: https://context7.com/valeriansaliou/sonic/llms.txt

The main configuration file for Sonic, detailing server, channel, search, and store settings. It controls aspects like logging, network interfaces, timeouts, authentication, query limits, and storage configurations.

```cfg
[server]
log_level = "error"  # debug, info, warn, error

[channel]
inet = "[::1]:1491"  # Listen address and port
tcp_timeout = 300    # Connection timeout in seconds
auth_password = "SecretPassword"  # Authentication password

[channel.search]
query_limit_default = 10    # Default search result limit
query_limit_maximum = 100   # Maximum allowed result limit
query_alternates_try = 4    # Number of typo corrections to try
suggest_limit_default = 5   # Default suggestion limit
suggest_limit_maximum = 20  # Maximum suggestion limit
list_limit_default = 100    # Default word list limit
list_limit_maximum = 500    # Maximum word list limit

[store.kv]
path = "./data/store/kv/"   # Key-value store path
retain_word_objects = 1000  # Max objects per word (sliding window)

[store.kv.database]
flush_after = 900           # Flush interval (seconds)
compress = true             # Enable Zstandard compression
parallelism = 2             # Compaction/flush threads
write_buffer = 16384        # Write buffer size (KB)
write_ahead_log = true      # Enable WAL for durability

[store.fst]
path = "./data/store/fst/"  # FST graph store path

[store.fst.graph]
consolidate_after = 180     # FST rebuild interval (seconds)
max_size = 2048             # Max FST size (KB)
max_words = 250000          # Max words in FST graph

```

--------------------------------

### TRIGGER - Execute Administrative Actions

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Trigger system operations such as FST consolidation or database backups, providing manual control over automated maintenance tasks.

```APIDOC
## TRIGGER - Execute Administrative Actions

### Description
Trigger system operations such as FST consolidation or database backups, providing manual control over automated maintenance tasks.

### Method
TRIGGER

### Endpoint
(Not applicable, command-line interface in control mode)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Trigger database consolidation (FST rebuild)
TRIGGER consolidate

# Trigger backup to specific file
TRIGGER backup /path/to/backup/sonic-backup-2025-12-30.db

# Trigger restore from backup file
TRIGGER restore /path/to/backup/sonic-backup-2025-12-30.db
```

### Response
#### Success Response (OK)
- **status** (string) - Indicates successful triggering of the action.

#### Response Example
```
OK
```
```

--------------------------------

### TRIGGER - Execute Administrative Actions

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Executes administrative actions such as FST consolidation or database backups. This command provides manual control over automated maintenance tasks, allowing for operations like rebuilding the index or creating backups. It also supports triggering restore operations.

```bash
# Trigger database consolidation (FST rebuild)
TRIGGER consolidate
OK

# Trigger backup to specific file
TRIGGER backup /path/to/backup/sonic-backup-2025-12-30.db
OK

# Trigger restore from backup file
TRIGGER restore /path/to/backup/sonic-backup-2025-12-30.db
OK

# Simple consolidate trigger
TRIGGER consolidate
OK
```

--------------------------------

### FLUSH Commands - Flush Index Data

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Remove indexed data at collection, bucket, or object level, enabling bulk deletion operations for index maintenance and cleanup.

```APIDOC
## FLUSHC, FLUSHB, FLUSHO - Flush Index Data

### Description
Remove indexed data at collection, bucket, or object level, enabling bulk deletion operations for index maintenance and cleanup. Commands return the count of affected items.

### Method
FLUSHC, FLUSHB, FLUSHO

### Endpoint
(Not applicable, command-line interface)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Flush entire collection (removes all data)
FLUSHC messages

# Flush specific bucket (removes all objects in bucket)
FLUSHB messages user:0dcde3a6

# Flush specific object (removes single object)
FLUSHO messages user:0dcde3a6 conversation:71f3d63b
```

### Response
#### Success Response (RESULT)
- **count** (integer) - The number of items affected by the flush operation.

#### Response Example
```
RESULT 1
```
```

--------------------------------

### PING - Health Check

Source: https://context7.com/valeriansaliou/sonic/llms.txt

Verify server connectivity and responsiveness, useful for health checks and connection keep-alive mechanisms.

```APIDOC
## PING - Health Check

### Description
Verify server connectivity and responsiveness, useful for health checks and connection keep-alive mechanisms in client libraries. This command has O(1) complexity and minimal overhead.

### Method
PING

### Endpoint
(Not applicable, command-line interface)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
PING
```

### Response
#### Success Response (PONG)
- **response** (string) - 'PONG'

#### Response Example
```
PONG
```
```