Query

The Query interface defines the contract for handling domain-specific queries in comby, ensuring consistency and traceability across the framework. Queries represent read operations that retrieve or filter data based on the provided criteria, encapsulated within the DomainQry.

type DomainQry any

type Query interface {
	// GetQueryUuid returns the unique identifier of the query.
	GetQueryUuid() string

	// SetQueryUuid sets the unique identifier for the query.
	SetQueryUuid(queryUuid string) error

	// GetTenantUuid returns the tenant's unique identifier.
	GetTenantUuid() string

	// SetTenantUuid sets the tenant's unique identifier.
	SetTenantUuid(tenantUuid string) error

	// GetDomain returns the domain associated with the query.
	GetDomain() string

	// SetDomain sets the domain for the query.
	SetDomain(domain string) error

	// GetDomainQryName returns the name of the underlying domain query type.
	GetDomainQryName() string

	// SetDomainQryName sets the name of the underlying DomainQry.
	SetDomainQryName(domanQryName string) error

	// GetDomainQryBytes returns the byte slice representation of the underlying domain query.
	GetDomainQryBytes() []byte

	// SetDomainQryBytes sets the byte slice representation of the underlying DomainQry.
	SetDomainQryBytes(data []byte) error

	// GetDomainQry returns the runtime representation of the underlying domain query.
	GetDomainQry() DomainQry

	// SetDomainQry sets the underlying domain query with the provided data.
	SetDomainQry(domainQry DomainQry) error

	// GetCreatedAt returns the timestamp when the query was created.
	GetCreatedAt() int64

	// SetCreatedAt sets the creation timestamp for the query.
	SetCreatedAt(createdAt int64) error

	// GetReqCtx returns the request context associated with the query.
	GetReqCtx() *RequestContext

	// SetReqCtx sets the request context for the query.
	SetReqCtx(reqCtx *RequestContext) error
}

The interface includes methods for managing the metadata and context associated with a query. The GetQueryUuid and SetQueryUuid methods handle the unique identifier for the query, ensuring traceability and allowing each query to be tracked independently. Similarly, the GetTenantUuid and SetTenantUuid methods associate the query with a specific tenant, enabling multi-tenant support.

The domain of the query is managed through the GetDomain and SetDomain methods, while the type of the underlying domain query is identified by GetDomainQryName and SetDomainQryName. These methods ensure that queries are correctly categorized and routed within the system. The domain-specific query data can be accessed and modified in serialized form using GetDomainQryBytes and SetDomainQryBytes or as a runtime object through GetDomainQry and SetDomainQry.

To support temporal operations, the GetCreatedAt and SetCreatedAt methods provide access to the query's creation timestamp. This allows for time-based filtering and tracking of query execution.

Additionally, the interface includes GetReqCtx and SetReqCtx methods to manage the RequestContext associated with the query. The RequestContext carries metadata and execution parameters, such as trace IDs and sender information, ensuring that the query is executed with full contextual awareness.

Base Query

The BaseQuery is a foundational implementation of the Query interface in comby, designed to standardize the structure and handling of queries within the framework. Queries in comby are used to retrieve or filter data, and the BaseQuery provides essential metadata, contextual information, and domain-specific query data to facilitate these operations. The structure of BaseQuery is defined as follows:

type BaseQuery struct {
	// QueryUuid is the unique identifier for the query.
	QueryUuid string `json:"queryUuid,omitempty"`

	// TenantUuid is the unique identifier of the tenant associated with the query.
	TenantUuid string `json:"tenantUuid,omitempty"`

	// Domain specifies the domain to which the query belongs.
	Domain string `json:"domain,omitempty"`

	// Domain query specific name (type) of the query.
	DomainQryName string `json:"domainQryName,omitempty"`

	// DomainQryBytes contains the byte array representation of the domain-specific query data.
	DomainQryBytes []byte `json:"domainQryBytes,omitempty"`

	// DomainQry holds the runtime representation of the domain-specific query data.
	DomainQry DomainQry `json:"-"`

	// CreatedAt is the timestamp when the query was created.
	CreatedAt int64 `json:"createdAt,omitempty"`

	// ReqCtx contains the request context information for the query.
	ReqCtx *RequestContext `json:"reqCtx,omitempty"`
}

The BaseQuery includes fields such as QueryUuid, a globally unique identifier that ensures traceability, and TenantUuid, which associates the query with a specific tenant, enabling multi-tenant support. The Domain and DomainQryName fields categorize the query within a specific domain and identify the type of domain-specific query being executed.

Domain-specific query data is managed in two forms: as a serialized byte array (DomainQryBytes) for storage and transmission, and as a runtime object (DomainQry) for processing. This dual representation ensures flexibility and compatibility with various processing requirements.

The CreatedAt field records the query's creation timestamp, allowing temporal tracking and debugging. Additionally, the ReqCtx field provides a RequestContext object that encapsulates metadata and execution parameters, such as sender information and trace IDs, ensuring that the query is processed within the appropriate context.

The BaseQuery is instantiated using the NewBaseQuery function, which sets default values for fields like QueryUuid, CreatedAt, and ReqCtx. For domain-specific queries, the NewQuery function simplifies the creation process by serializing the provided DomainQry and attaching it to the BaseQuery.

Usage

The NewQuery function in comby simplifies the creation of domain-specific queries, allowing developers to seamlessly integrate them into the framework.

For example, consider a domain query CustomModelRequest designed to retrieve the current order using a custom readmodel. This query includes fields only one required filed: OrderUuid.

To create a new query, use the following approach:

// domain query
type CustomModelRequest struct {
	OrderUuid string `json:"orderUuid"`
}

// create new query
qry, _ := comby.NewQuery("Order", &CustomModelRequest{
	OrderUuid:   "KnownOrderUuid",
})

// dispatch to facade ...

Here, the NewQuery function serializes the CustomModelRequest and attaches it to a newly created BaseQuery. The resulting query includes metadata such as the query's unique identifier (QueryUuid), domain (Domain), and serialized data (DomainQryBytes), making it ready for processing.

Once the query is created, it can be dispatched to the Facade for processing, where it will trigger the corresponding QueryHandler.