Skip to content

feat(php): Add Core Valkey Search commands#171

Open
edlng wants to merge 1 commit intovalkey-io:mainfrom
edlng:edlng/valkey-search-core
Open

feat(php): Add Core Valkey Search commands#171
edlng wants to merge 1 commit intovalkey-io:mainfrom
edlng:edlng/valkey-search-core

Conversation

@edlng
Copy link
Copy Markdown
Collaborator

@edlng edlng commented Mar 24, 2026

feat(php): add Valkey Search commands (ftCreate, ftDropIndex, ftList, ftSearch, ftInfo, ftAggregate, ftAliasAdd, ftAliasDel, ftAliasUpdate, ftAliasList)

Summary

Adds FT.* commands for Valkey Search across both standalone (ValkeyGlide) and cluster (ValkeyGlideCluster) clients.

This is the first of two PRs splitting the original valkey-search branch. The CI changes (Docker-based server startup for the Search module) follow in a separate PR.

Issue link

Closes #163

Features / Behaviour Changes

  • ftCreate — create a search index with schema definition and options (ON, PREFIX, SCORE, LANGUAGE, vector fields, etc.)
  • ftDropIndex — drop an existing index
  • ftList — list all indexes
  • ftSearch — run a search query with options (RETURN, PARAMS, SORTBY, LIMIT, NOCONTENT, shard/consistency flags)
  • ftInfo — get index metadata with optional scope (LOCAL, PRIMARY, CLUSTER) and shard flags
  • ftAggregate — run an aggregation pipeline (GROUPBY, REDUCE, SORTBY, APPLY, FILTER, LIMIT, LOAD, PARAMS, DIALECT)
  • ftAliasAdd — add an alias to an index
  • ftAliasDel — remove an alias
  • ftAliasUpdate — point an alias at a different index
  • ftAliasList — list all alias-to-index mappings

Implementation

Follows the existing command pattern in the repo:

  • PHP stubs in valkey_glide.stub.php and valkey_glide_cluster.stub.php
  • Shared argument builders and FFI dispatch in valkey_glide_ft_common.c / .h
  • Command-specific parsing in valkey_glide_ft_commands.c
  • Method macros invoked in valkey_z_php_methods.c (standalone) and valkey_glide_cluster.c (cluster)
  • Build registration in config.m4 and package.xml

Limitations

  • Tests require a Valkey server with the Search module loaded. Without it, tests skip gracefully.
  • The alias test (testFtAliasOperations) is currently skipped — valkey-search 1.2 images don't support FT.ALIASADD yet. Will re-enable once newer images are available.
  • The aggregate test (testFtAggregateBicycles) is also skipped due to query syntax differences in valkey-search 1.2. Same plan.

Testing

Integration tests in tests/ValkeyGlideValkeySearchTest.php covering:

  • Index creation with various field types (TEXT, NUMERIC, TAG, VECTOR) and options
  • Duplicate index error handling
  • Drop and list round-trip
  • KNN vector search with PARAMS and RETURN
  • Search on non-existent index (error path)
  • ftInfo with scope and shard flags
  • Index-level options: SCORE, LANGUAGE, SKIPINITIALSCAN, NOSTOPWORDS, MINSTEMSIZE, NOOFFSETS
  • Field options: nostem, sortable, weight, withsuffixtrie, nosuffixtrie
  • RETURN with field aliases
  • Alias lifecycle (add, list, update, delete, error on duplicate/non-existent) — skipped pending image support
  • GROUPBY + REDUCE aggregate pipeline — skipped pending image support

Checklist

Before submitting the PR make sure the following are checked:

  • This Pull Request is related to one issue.
  • Commit message has a detailed description of what changed and why.
  • Tests are added or updated.
  • CHANGELOG.md and documentation files are updated.
  • Destination branch is correct - main or release
  • Create merge commit if merging release branch into main, squash otherwise.

Signed-off-by: Edward Liang <edward.liang@improving.com>
@edlng edlng force-pushed the edlng/valkey-search-core branch from 50bd58e to dfe5ec0 Compare March 25, 2026 15:15
@edlng edlng marked this pull request as ready for review March 25, 2026 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

(valkey-search): Add support for the Valkey Search module

1 participant