GoodMemGoodMem
ReferenceClient SDKsGo

Embedders

Go SDK reference for embedder configurations: creation, lookup, listing, updates, and deletion.

package goodmem // import "fury.io/pairsys/goodmem"

Embedder management — provider configuration + lifecycle.

Methods are called as client.Embedders().<Method>(ctx, ...) on a *goodmem.Client. Service: EmbeddersService.

Index

type EmbeddersService

type EmbeddersService struct{ … }

Access this service as client.Embedders() on a *goodmem.Client. Its methods follow.

func (s *EmbeddersService) Create

func (s *EmbeddersService) Create(ctx context.Context, req *models.EmbedderCreationRequest, apiKey string) (*models.EmbedderResponse, error)

Creates an embedder configuration for use with memory spaces. If ownerId is omitted, the authenticated principal becomes the owner; CREATE_EMBEDDER is evaluated against that proposed embedder and owner. Returns 409 when an equivalent embedder configuration already exists for the owner. See the embedder provider guide for provider-specific configuration.

HTTP — POST /v1/embedders

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • req (*models.EmbedderCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.
  • apiKey (string) — bare provider API key. The convenience layer auto-fills provider / endpoint / dimensionality from the bundled model registry (keyed by the request's model identifier) and converts the key to structured credentials. Pass "" to keep any credentials already set on req.

Returns — (*models.EmbedderResponse, error)

Example

embedder, err := client.Embedders().Create(ctx, &models.EmbedderCreationRequest{
	DisplayName:     "Doc Embedder",
	ModelIdentifier: "text-embedding-3-small",
	Labels:          map[string]string{"env": "docs"},
}, "sk-...")
if err != nil {
	log.Fatal(err)
}
_ = embedder

func (s *EmbeddersService) Get

func (s *EmbeddersService) Get(ctx context.Context, id string, params *EmbeddersGetParams) (*models.EmbedderResponse, error)

Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER on the requested embedder. The service distinguishes a missing embedder from an existing embedder the caller cannot read. This is a read-only operation with no side effects.

HTTP — GET /v1/embedders/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the embedder to retrieve
  • params (*EmbeddersGetParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.EmbedderResponse, error)

Example

embedder, err := client.Embedders().Get(ctx, "your-embedder-id", nil)
if err != nil {
	log.Fatal(err)
}
_ = embedder.DisplayName

func (s *EmbeddersService) List

func (s *EmbeddersService) List(ctx context.Context, params *EmbeddersListParams) (*models.ListEmbeddersResponse, error)

Retrieves a list of embedder configurations accessible to the caller, with optional filtering.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

AUTHORIZATION: Requires LIST_EMBEDDER on the GoodMem instance. Each returned embedder must also be visible through READ_EMBEDDER; unauthorized embedders are filtered in PostgreSQL. The ownerId parameter filters that already-authorized result set and does not grant additional visibility. This is a read-only operation with no side effects.

HTTP — GET /v1/embedders

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • params (*EmbeddersListParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.ListEmbeddersResponse, error)

Example

resp, err := client.Embedders().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for _, emb := range resp.Embedders {
	_ = emb.EmbedderID
	_ = emb.DisplayName
}

func (s *EmbeddersService) Update

func (s *EmbeddersService) Update(ctx context.Context, id string, req *models.UpdateEmbedderRequest) (*models.EmbedderResponse, error)

Updates explicitly supplied embedder fields; at least one mutable field is required. Field omission and reset semantics are defined by the request schema, and providerType cannot be changed. Returns 409 if the resulting configuration duplicates another embedder for the owner, and 412 when model-defining fields are changed while the embedder is in use. Requires UPDATE_EMBEDDER on the requested embedder. See the embedder provider guide for provider-specific configuration.

HTTP — PUT /v1/embedders/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the embedder to update
  • req (*models.UpdateEmbedderRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.EmbedderResponse, error)

Example

updated, err := client.Embedders().Update(ctx, "your-embedder-id", &models.UpdateEmbedderRequest{
	DisplayName: goodmem.Ptr("Doc Embedder (updated)"),
	MergeLabels: map[string]string{"version": "2"},
})
if err != nil {
	log.Fatal(err)
}
_ = updated.EmbedderID

func (s *EmbeddersService) Delete

func (s *EmbeddersService) Delete(ctx context.Context, id string) error

Permanently deletes an embedder configuration. This operation cannot be undone and removes the embedder record and securely deletes stored credentials.

IMPORTANT: This does NOT invalidate or delete embeddings previously created with this embedder - existing embeddings remain accessible.

CONFLICT: Returns HTTP 409 Conflict if the embedder is still referenced by a space. Requires DELETE_EMBEDDER on the requested embedder.

HTTP — DELETE /v1/embedders/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the embedder to delete

Returns — error — nil on success.

Example

err := client.Embedders().Delete(ctx, "your-embedder-id")
if err != nil {
	log.Fatal(err)
}

type EmbedderCreationRequest

type EmbedderCreationRequest struct{ … }

Request body for creating a new Embedder. An Embedder represents a configuration for vectorizing content.

  • DisplayName (string, wire displayName) — User-facing name of the embedder
  • Description (string, optional, wire description) — Description of the embedder
  • ProviderType (models.ProviderType, wire providerType) — Type of embedding provider
  • EndpointURL (string, wire endpointUrl) — Base HTTP(S) endpoint for provider requests. Gemini endpoint URLs must not contain query parameters.
  • APIPath (string, optional, wire apiPath) — Provider-relative request path. Omit or send blank to use the provider default. For Gemini, this is an API version: /v1beta for Developer and /v1 for Google Cloud.
  • ModelIdentifier (string, wire modelIdentifier) — Model identifier
  • Dimensionality (int32, wire dimensionality) — Output vector dimensions
  • DistributionType (models.DistributionType, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
  • MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
  • SupportedModalities ([]models.Modality, optional, wire supportedModalities) — Supported content modalities (defaults to TEXT if not provided)
  • Credentials (models.EndpointAuthentication, optional, wire credentials) — Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local or proxy providers.
  • Labels (map[string]string, optional, wire labels) — User-defined labels for categorization
  • Version (string, optional, wire version) — Version information
  • MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL
  • OwnerID (string, optional, wire ownerId) — Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_EMBEDDER is evaluated against the proposed embedder and owner.
  • EmbedderID (string, optional, wire embedderId) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
  • DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to infer the dialect from apiPath, the model catalog, or the native text default.
  • GeminiEndpointConfig (models.GeminiEndpointConfig, optional, wire geminiEndpointConfig) — Gemini backend routing. Valid only for the GEMINI provider. Omit to use the Developer API; when present, backend is required and the gRPC service validates the backend-specific projectId and location contract.

type DistributionType

type DistributionType string

Type of embedding distribution produced by the embedder

String enum (type DistributionType string): "DENSE" · "SPARSE"

type GeminiEndpointConfig

type GeminiEndpointConfig struct{ … }

Gemini backend routing. DEVELOPER does not use projectId or location; GOOGLE_CLOUD requires projectId and defaults an omitted location to global.

  • Backend (models.GeminiApiBackend, wire backend) — Google API surface. UNSPECIFIED is invalid when this configuration is supplied on a write.
  • ProjectID (string, optional, wire projectId) — Google Cloud resource project. Required for GOOGLE_CLOUD and unused for DEVELOPER; this is distinct from the ADC quota project.
  • Location (string, optional, wire location) — Google Cloud location. Valid only for GOOGLE_CLOUD; omission defaults to global.

type GeminiApiBackend

type GeminiApiBackend string

Google API surface used by a Gemini embedder

String enum (type GeminiApiBackend string): "UNSPECIFIED" · "DEVELOPER" · "GOOGLE_CLOUD"

type EmbedderResponse

type EmbedderResponse struct{ … }

Embedder configuration information

  • EmbedderID (string, wire embedderId) — Unique identifier of the embedder
  • DisplayName (string, wire displayName) — User-facing name of the embedder
  • Description (string, optional, wire description) — Description of the embedder
  • ProviderType (models.ProviderType, wire providerType) — Type of embedding provider
  • EndpointURL (string, wire endpointUrl) — Canonical base HTTP(S) endpoint used for provider requests.
  • APIPath (string, optional, wire apiPath) — Configured provider-relative request path. For Gemini, this is the selected API version: /v1beta for Developer or /v1 for Google Cloud.
  • ModelIdentifier (string, wire modelIdentifier) — Model identifier
  • Dimensionality (int32, wire dimensionality) — Output vector dimensions
  • DistributionType (models.DistributionType, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
  • MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
  • SupportedModalities ([]models.Modality, wire supportedModalities) — Supported content modalities
  • Credentials (models.EndpointAuthentication, optional, wire credentials) — Stored credentials; present only when GetEmbedder explicitly requests them and the caller has READ_EMBEDDER_CREDENTIALS. Always omitted from create, update, and list responses.
  • Labels (map[string]string, wire labels) — User-defined labels for categorization
  • Version (string, optional, wire version) — Version information
  • MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL
  • OwnerID (string, wire ownerId) — Owner ID of the embedder
  • CreatedAt (int64, wire createdAt) — Creation timestamp (milliseconds since epoch)
  • UpdatedAt (int64, wire updatedAt) — Last update timestamp (milliseconds since epoch)
  • CreatedByID (string, wire createdById) — ID of the user who created the embedder
  • UpdatedByID (string, wire updatedById) — ID of the user who last updated the embedder
  • DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.
  • GeminiEndpointConfig (models.GeminiEndpointConfig, optional, wire geminiEndpointConfig) — Persisted Gemini backend routing; present only for Gemini embedder resources.

type ListEmbeddersResponse

type ListEmbeddersResponse struct{ … }

Response containing a list of embedders

type UpdateEmbedderRequest

type UpdateEmbedderRequest struct{ … }

Request body for updating an existing Embedder. Only fields that should be updated need to be included. supportedModalities is creation-time only and cannot be changed here.

  • DisplayName (string, optional, wire displayName) — User-facing name of the embedder
  • Description (string, optional, wire description) — Description of the embedder
  • EndpointURL (string, optional, wire endpointUrl) — Replacement base HTTP(S) endpoint. Omit to preserve the stored value. Gemini endpoint URLs must not contain query parameters.
  • APIPath (string, optional, wire apiPath) — Replacement provider-relative request path. Omit to preserve the stored value, except that changing the Gemini backend without apiPath selects that backend's default; send blank to restore the provider default. For Gemini, this is an API version: /v1beta for Developer and /v1 for Google Cloud.
  • ModelIdentifier (string, optional, wire modelIdentifier) — Model identifier
  • Dimensionality (int32, optional, wire dimensionality) — Output vector dimensions
  • DistributionType (models.DistributionType, optional, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
  • MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
  • Credentials (models.EndpointAuthentication, optional, wire credentials) — Replace stored credentials. Omit this field to preserve the current credentials; a present empty payload is invalid and never clears them.
  • ReplaceLabels (map[string]string, optional, wire replaceLabels) — Replace all existing labels with these (mutually exclusive with mergeLabels)
  • MergeLabels (map[string]string, optional, wire mergeLabels) — Merge these labels with existing ones (mutually exclusive with replaceLabels)
  • Version (string, optional, wire version) — Version information
  • MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL
  • DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — Update the DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to preserve the stored dialect. Changing apiPath to a recognized canonical DashScope dialect infers its matching dialect; a custom path preserves an existing dialect, while a legacy null dialect is inferred.
  • GeminiEndpointConfig (models.GeminiEndpointConfig, optional, wire geminiEndpointConfig) — When present, atomically replaces the complete Gemini backend routing configuration. Valid only for a GEMINI embedder. Omit to preserve the stored configuration; the gRPC service validates the backend-specific projectId and location contract.

Go SDK

Install and configure the GoodMem Go SDK. Reference context-driven clients, resource methods, errors, and shared data models.

Rerankers

Go SDK reference for reranker configurations: creation, lookup, listing, updates, and deletion.

On this page

Indextype EmbeddersServicefunc (s *EmbeddersService) Createfunc (s *EmbeddersService) Getfunc (s *EmbeddersService) Listfunc (s *EmbeddersService) Updatefunc (s *EmbeddersService) Deletetype EmbedderCreationRequesttype DistributionTypetype GeminiEndpointConfigtype GeminiApiBackendtype EmbedderResponsetype ListEmbeddersResponsetype UpdateEmbedderRequest