test: docker-compose passes server flags via REDIS_ARGS, which the official redis image ignores

[nkanu17]

Summary

tests/docker-compose.yml passes Redis server flags through the REDIS_ARGS environment variable. REDIS_ARGS is a redis-stack image convention: the redis-stack entrypoint reads it and appends it to the server command line. The official docker.io/library/redis image used by this compose file does not read it at all, so none of these flags are ever applied to the test container.

services:
  redis:
    image: "${REDIS_IMAGE:-redis:8.4}"
    environment:
      # Pin the RediSearch worker pool to 0 (single-threaded, foreground
      # execution). Redis 8.8 changed the default from 0 to a multithreaded
      # background executor, which surfaces a race where FT.SEARCH can return
      # nil fields for docs that expire mid-query -- the source of flaky
      # redis:latest CI runs. WORKERS=0 avoids the race and is already the
      # default on the pinned 8.2/8.4 images, so this is a no-op there.
      - "REDIS_ARGS=--save '' --appendonly no --search-workers ${REDIS_SEARCH_WORKERS:-0}"

The affected settings are --save '', --appendonly no, and --search-workers.

Evidence

Verified locally against redis:latest (Redis 8.10.0):

A container started with the compose file's environment reports the multithreaded default rather than 0:

$ docker run -d -e "REDIS_ARGS=--save '' --appendonly no --search-workers 0" redis:latest
$ docker exec <id> redis-cli CONFIG GET search-workers
search-workers
14

A distinctive setting confirms the variable is ignored entirely rather than partially parsed:

$ docker run -d -e "REDIS_ARGS=--maxmemory 123mb" redis:latest
$ docker exec <id> redis-cli CONFIG GET maxmemory
maxmemory
0

(appendonly no happens to match the image default, so it is not evidence either way.)

Impact

This is test infrastructure only. No shipped redisvl code is affected, so no released version has a defect from this. The consequence is that the test Redis does not have the configuration the compose file says it has, and the --search-workers 0 pin added to reduce flaky CI runs on newer Redis images has never taken effect.

Suggested fix

Pass the flags as real server arguments via a compose command: entry instead of an environment variable:

    command: ["redis-server", "--save", "", "--appendonly", "no", "--search-workers", "${REDIS_SEARCH_WORKERS:-0}"]

Verification worth doing as part of the fix:

• REDIS_IMAGE=redis:latest docker compose -f tests/docker-compose.yml up -d, then redis-cli CONFIG GET search-workers returns 0.
• Same check against the pinned redis:8.2 and redis:8.4 images, where 0 is already the default so the change should be a no-op.
• Confirm --save '' still results in no RDB save points, since quoting an empty argument in compose command form differs from shell quoting.

Note on the flaky CI runs

The compose comment attributes flaky redis:latest runs to a Redis 8.8 multithreaded-search race where FT.SEARCH can return nil fields for docs expiring mid-query. That attribution should be treated as unconfirmed, and this fix should not be assumed to resolve the flakiness.

Attempting to reproduce it: loading 7 documents and querying immediately with no wait, 150 iterations against redis:latest 8.10.0 with search-workers 14, and again with search-workers 0, produced no shortfall in either configuration. Vector queries and filter queries both saw all 7 documents on every iteration.

The redis:latest matrix jobs do fail nondeterministically with a consistent signature of fewer documents than expected, on a rotating cast of tests (test_unf_noindex_integration, test_query_cosine_distance_un_normalized, and test_hybrid.py hybrid queries returning zero rows). Root-causing that is separate work from this issue.

[nkanu17]

Root cause of the redis:latest flakiness, confirmed

The mechanism described in the comment being replaced is real, and #659 does fix it. An earlier attempt of mine failed to reproduce it and I wrongly reported the attribution as unconfirmed. That attempt was single-threaded against an idle server, which is exactly the condition under which the bug does not appear.

With concurrent writers, it reproduces readily. The test harness below creates an index, loads 3 documents, and queries immediately expecting all 3, across 8 threads, 60 iterations each (480 total), against redis:latest (8.10.0).

configuration	shortfalls	documents seen at first query
search-workers 14 (image default), 1 CPU	17/480	0, 1, or 2 instead of 3
search-workers 14 (image default), unconstrained CPU	17/480	0, 1, or 2 instead of 3
search-workers 0	0/480	always 3

The distribution of partial results matches the CI failures exactly: sometimes zero documents (as in test_hybrid.py returning 0 of 7), sometimes 1 or 2 of 3 (as in test_unf_noindex_integration asserting ['apple'] == ['Banana', 'ZEBRA', 'apple']).

The writes land; the index lags

For every one of 30 shortfall events in a follow-up run, all 3 hashes were already present in the keyspace, so this is not a lost or delayed write. Re-querying in a tight loop showed the index catching up in every case:

shortfall events: 30
docs present in keyspace during every shortfall: True (3 of 3 expected)
index caught up in all cases: 30/30
convergence delay ms: min=0.8  median=1.6  max=2.6
docs seen at first query: 0 x14, 1 x9, 2 x7

So on Redis 8.8+ with the multithreaded RediSearch worker pool enabled, FT.SEARCH briefly loses read-your-writes consistency, for roughly 1 to 3 ms, when writes and queries are concurrent. search-workers 0 restores synchronous foreground indexing and eliminates it entirely.

What this means here

Because REDIS_ARGS was ignored by the official image, search-workers has been at the image default (equal to the core count) on every redis:latest CI job, so the intended mitigation was never actually in effect. Applying the flags via command: in #659 makes --search-workers 0 take hold, which should resolve this family of nondeterministic failures on the redis:latest matrix jobs.

Worth noting separately: this is server behavior and it affects library users too, not just the test suite. Anyone calling load() and then querying immediately, concurrently with other writers, on Redis 8.8+ can see partial results for a few milliseconds. Filed as a separate issue for documentation.