io.lettuce.core.search

Class FieldValue

java.lang.Object

io.lettuce.core.search.FieldValue

public final class FieldValue
extends Object

A single field value from a Redis search reply, retained in the exact shape returned by the server.

A search reply carries no per-field type information, so the client cannot know whether a value is textual (a TEXT/NUMERIC field or an aggregation expression) or binary (a vector embedding returned through RETURN or LOAD). FieldValue keeps the exact bytes and lets the caller decide how to read them: asString() for text and numbers, asBytes() for binary content where UTF-8 decoding would corrupt the value.

Most field values are scalars, but aggregation reducers such as FT.AGGREGATE REDUCE COLLECT produce nested column values. A FieldValue therefore has a FieldValue.Kind: FieldValue.Kind.SCALAR for raw bytes, FieldValue.Kind.ARRAY for a list of nested values, FieldValue.Kind.MAP for named nested values, and FieldValue.Kind.NULL for a server-returned null. A collected column is an FieldValue.Kind.ARRAY with one element per collected entry; read it via asList() and read each entry via asMap(), which normalizes the protocol-specific entry shape (RESP3 returns each entry as a map, RESP2 as a flat key/value array).

The server can also return a field with a null value (for example a JSON null loaded through RETURN or LOAD). Such a field is kept with its key present and reported by isNull(); all accessors return null for it. The FieldValue itself is never null in SearchReply.SearchResult.getFields(); a field that was not returned at all is represented by the absence of its key. Reading a non-null value through an accessor of a different kind (for example asString() on an FieldValue.Kind.ARRAY) throws IllegalStateException.

Since:

7.8

Author:

Viktoriya Kutsarova

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FieldValue.Kind The shape of a FieldValue.

Method Summary

Modifier and Type	Method and Description
static FieldValue	array(List<FieldValue> elements) Creates an array field value from the given elements.
byte[]	asBytes() Gets the raw field bytes, exactly as returned by the server.
List<FieldValue>	asList() Gets the elements of an array field value, for example the entries of a collected aggregation column.
Map<String,FieldValue>	asMap() Gets the field value as a map of named nested values.
String	asString() Gets the field value decoded as UTF-8 text.
String	asString(Charset charset) Gets the field value decoded as text using the given charset.
boolean	equals(Object o)
FieldValue.Kind	getKind() Returns the FieldValue.Kind of this field value.
int	hashCode()
boolean	isNull() Reports whether the server returned this field with a null value.
static FieldValue	map(Map<String,FieldValue> entries) Creates a map field value from the given entries, preserving their iteration order.
static FieldValue	nullValue() Returns the FieldValue representing a server-returned null value.
static FieldValue	of(byte[] value) Wraps the raw bytes of a scalar field value.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

of

public static FieldValue of(byte[] value)

Wraps the raw bytes of a scalar field value.

Parameters:

value - the raw field value exactly as returned by the server. Must not be null.

Returns:

a FieldValue.Kind.SCALAR FieldValue view over the given bytes

Since:

7.8

array

public static FieldValue array(List<FieldValue> elements)

Creates an array field value from the given elements.

Parameters:

elements - the array elements. Must not be null and must not contain null elements (use nullValue() for a null element).

Returns:

a FieldValue.Kind.ARRAY FieldValue holding a copy of the given elements

Since:

7.8

map

public static FieldValue map(Map<String,FieldValue> entries)

Creates a map field value from the given entries, preserving their iteration order.

Parameters:

entries - the map entries. Must not be null and must not contain null keys or values (use nullValue() for a null value).

Returns:

a FieldValue.Kind.MAP FieldValue holding a copy of the given entries

Since:

7.8

nullValue

public static FieldValue nullValue()

Returns the FieldValue representing a server-returned null value.

Returns:

the shared FieldValue.Kind.NULL instance

Since:

7.8

getKind

public FieldValue.Kind getKind()

Returns the FieldValue.Kind of this field value.

Returns:

the kind, never null

Since:

7.8

asBytes

public byte[] asBytes()

Gets the raw field bytes, exactly as returned by the server. Use this accessor for binary fields such as vector embeddings, where UTF-8 decoding would corrupt the value.

Returns:

the raw field bytes, or null if the server returned a null value (see isNull()). This is the backing array and must not be modified.

Throws:

IllegalStateException - if this value is an FieldValue.Kind.ARRAY or a FieldValue.Kind.MAP

Since:

7.8

asString

public String asString()

Gets the field value decoded as UTF-8 text. This suits textual and numeric fields. Binary values (for example vector embeddings) are not valid UTF-8 and are corrupted by this view; read those via asBytes().

Returns:

the field value decoded as UTF-8, or null if the server returned a null value (see isNull())

Throws:

IllegalStateException - if this value is an FieldValue.Kind.ARRAY or a FieldValue.Kind.MAP

Since:

7.8

asString

public String asString(Charset charset)

Gets the field value decoded as text using the given charset.

Parameters:

charset - the charset to decode with

Returns:

the decoded field value, or null if the server returned a null value (see isNull())

Throws:

IllegalStateException - if this value is an FieldValue.Kind.ARRAY or a FieldValue.Kind.MAP

Since:

7.8

asList

public List<FieldValue> asList()

Gets the elements of an array field value, for example the entries of a collected aggregation column.

Returns:

an unmodifiable list of the array elements, or null if the server returned a null value (see isNull())

Throws:

IllegalStateException - if this value is a FieldValue.Kind.SCALAR or a FieldValue.Kind.MAP

Since:

7.8

asMap

public Map<String,FieldValue> asMap()

Gets the field value as a map of named nested values.

A FieldValue.Kind.MAP value is returned directly. An FieldValue.Kind.ARRAY value is interpreted as a flat list of key/value pairs — the shape RESP2 uses for a collected aggregation entry — where each key must be a scalar and is decoded as UTF-8; an array of odd length, or one whose key positions hold non-scalar values, does not represent key/value pairs and is rejected. This makes a collected entry readable the same way on RESP2 and RESP3. Note that any even-length array of scalars is accepted by this interpretation, including values (for example a TOLIST column) that the server did not produce as key/value pairs — it is the caller's responsibility to apply this view only to fields that hold pairs.

Returns:

an unmodifiable, ordered map of the named nested values, or null if the server returned a null value (see isNull())

Throws:

IllegalStateException - if this value is a FieldValue.Kind.SCALAR, or an FieldValue.Kind.ARRAY that does not represent key/value pairs

Since:

7.8

isNull

public boolean isNull()

Reports whether the server returned this field with a null value. When true, all accessors return null.

Returns:

true if this field value is null

Since:

7.8

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object