Package com.linkedin.venice.client.store

Interface AvroGenericStoreClient<K,V>

Type Parameters:
V -
All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
AvroGenericReadComputeStoreClient<K,V>, AvroSpecificStoreClient<K,V>, DaVinciClient<K,V>, SeekableDaVinciClient<K,V>
All Known Implementing Classes:
AbstractAvroStoreClient, AvroBlackHoleResponseStoreClientImpl, AvroGenericDaVinciClient, AvroGenericSeekableDaVinciClient, AvroGenericStoreClientImpl, AvroSpecificDaVinciClient, AvroSpecificSeekableDaVinciClient, AvroSpecificStoreClientImpl, DelegatingAvroGenericDaVinciClient, DelegatingAvroStoreClient, DelegatingStoreClient, DispatchingAvroGenericStoreClient, DispatchingAvroSpecificStoreClient, DispatchingVsonStoreClient, DualReadAvroGenericStoreClient, DualReadAvroSpecificStoreClient, InternalAvroStoreClient, InternalAvroStoreClient, LoadControlledAvroGenericStoreClient, LoadControlledAvroSpecificStoreClient, LoggingTrackingStoreClient, RetriableAvroGenericStoreClient, RetriableAvroSpecificStoreClient, RetriableStoreClient, SpecificLoggingTrackingStoreClient, SpecificRetriableStoreClient, SpecificStatTrackingStoreClient, StatsAvroGenericDaVinciClient, StatsAvroGenericStoreClient, StatsAvroSpecificDaVinciClient, StatsAvroSpecificStoreClient, StatTrackingStoreClient, VersionSpecificAvroGenericDaVinciClient, VsonGenericStoreClientImpl
public interface AvroGenericStoreClient<K,V> extends Closeable
Venice avro generic client to communicate with Venice backend for key-value lookup.

  • Method Details

    • get

      CompletableFuture<V> get(K key) throws VeniceClientException
      Lookup the value by given key, and get(key).get() will return null if it doesn't exist. For now, if any backend error/exception happens, get(Object key).get() will throw ExecutionException, which is a wrapper of the real exception.
      Parameters:
      key -
      Returns:
      Throws:
      VeniceClientException

    • get

      default CompletableFuture<V> get(K key, V reusedValue) throws VeniceClientException
      Similar to get(Object) except that it allows passing in a instance, to minimize GC.
      Throws:
      VeniceClientException

    • batchGet

      default CompletableFuture<Map<K,V>> batchGet(Set<K> keys) throws VeniceClientException
      Get the values associated with the given keys and return them in a map of keys to values. Note that the returned map will only contain entries for the keys which have a value associated with them.
      Parameters:
      keys -
      Returns:
      Throws:
      VeniceClientException

    • streamingBatchGet

      default CompletableFuture<VeniceResponseMap<K,V>> streamingBatchGet(Set<K> keys) throws VeniceClientException
      Get the values associated with the given keys and return them in a map of keys to values. When time-out happens for the following invocation: streamingBatchGet(keys).get(waitingTime, unit); This function will return the available response instead of throwing a TimeoutException. It means this function could return either full response or partial response.
      Parameters:
      keys -
      Returns:
      Throws:
      VeniceClientException

    • streamingBatchGet

      void streamingBatchGet(Set<K> keys, StreamingCallback<K,V> callback) throws VeniceClientException
      Streaming interface for batchGet(Set). You can find more info in StreamingCallback.
      Parameters:
      keys -
      callback -
      Throws:
      VeniceClientException

    • compute

      ComputeRequestBuilder<K> compute()
      This API allows performing transformations (projection, vector arithmetic and aggregations like count) on the values associated with the given set of keys. Check out ComputeRequestBuilder for details on the available operations.
      See Also:

    • start

      void start() throws VeniceClientException
      Throws:
      VeniceClientException

    • close

      void close()
      Release the internal resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • getStoreName

      String getStoreName()

    • getKeySchema

      @Deprecated org.apache.avro.Schema getKeySchema()
      Deprecated.
      This method is considered deprecated. Please use StoreSchemaFetcher.getKeySchema() to fetch key schema instead.
      Get key schema.

    • getLatestValueSchema

      @Deprecated org.apache.avro.Schema getLatestValueSchema()
      Deprecated.
      This method is considered deprecated. Please use StoreSchemaFetcher.getLatestValueSchemaEntry() to fetch latest value schema instead.
      Get the latest value schema known in current store client. This function doesn't guarantee it will return the latest schema if you add a new value schema when current store client is running.

    • decompressAndDeserialize

      default V decompressAndDeserialize(ByteBuffer rawValue, int version, K key) throws VeniceClientException
      Re-entry point for callers that obtained Venice-format raw value bytes from a path other than the standard Venice routing layer (e.g. an external storage system holding the same wire bytes) and want to run those bytes through the Fast Client's existing decompression + Avro deserialization pipeline without duplicating that logic.

      This entry point is Fast Client only — implemented by com.linkedin.venice.fastclient.DispatchingAvroGenericStoreClient and forwarded by Fast Client's DelegatingAvroStoreClient wrapper chain. Thin-client implementations inherit the throwing default because they lack the metadata refresh loop that supplies per-version compression state.

      Wire format. rawValue must hold the bytes exactly as Venice's storage layer writes them on disk / to an external sink: a 4-byte big-endian int writer-schema id followed by the post-compression Avro-serialized value body. This matches what com.linkedin.venice.writer.DualWriteVeniceWriter#toRocksDbFormattedValue produces for the dual-write external sink. The seam reads the schema id from those 4 bytes (so a store that has schema-evolved will still decode old payloads with their original writer schema), resolves the per-version compressor from StoreMetadata, decompresses the remainder, and deserializes with the embedded schema id.

      Parameters:
      rawValue - the value payload, prefixed by a 4-byte big-endian writer-schema id. Must not be null and must have at least 4 bytes.
      version - the store version the rawValue bytes were written under. Used to resolve the per-version compressor (including any ZSTD dictionary). Throws if the version is unknown to the metadata layer.
      key - the key that produced this value (used only for error messages and tracing)
      Returns:
      the deserialized value
      Throws:
      UnsupportedOperationException - by the default — including on every thin-client implementation
      VeniceClientException - if the version is unknown, or if decompression or deserialization fails
      IllegalArgumentException - if rawValue is null or shorter than 4 bytes

    • registerVersionSwitchListener

      default void registerVersionSwitchListener(StoreVersionSwitchListener listener)
      Register a StoreVersionSwitchListener that fires when the underlying metadata layer observes a change to the store's current serving version.

      Fast Client only. Thin-client implementations inherit the throwing default — there is no metadata refresh loop on the thin client, so version-switch transitions are not observable. See com.linkedin.venice.fastclient.DispatchingAvroGenericStoreClient for the Fast Client implementation and StoreVersionSwitchListener for threading and exception semantics.

      Registration timing. Listeners must be registered before start() to observe the initial transition committed by the first metadata refresh. Listeners registered after start() returns observe only subsequent transitions (and re-entrant registration from inside a callback observes only subsequent transitions as well). Callers needing the initial transition should use the non-starting factory entry point (com.linkedin.venice.fastclient.factory.ClientFactory#getGenericStoreClient), register their listeners, then call start() on the returned client.

      Registration is thread-safe.

      Throws:
      IllegalArgumentException - if listener is null
      UnsupportedOperationException - by the default — including on every thin-client implementation

    • registerStoreConfigChangeListener

      default void registerStoreConfigChangeListener(StoreConfigChangeListener listener)
      Register a StoreConfigChangeListener that fires when the underlying metadata layer observes a change to the store-level config snapshot (e.g. operator-driven externalStorageReadMode flip).

      Fast Client only. Thin-client implementations inherit the throwing default. See com.linkedin.venice.fastclient.DispatchingAvroGenericStoreClient for the Fast Client implementation and StoreConfigChangeListener for threading and exception semantics.

      Registration timing. Same as registerVersionSwitchListener(com.linkedin.venice.client.store.listeners.StoreVersionSwitchListener) — register before start() to observe the initial snapshot; post-start registration observes only subsequent changes.

      Throws:
      IllegalArgumentException - if listener is null
      UnsupportedOperationException - by the default — including on every thin-client implementation