driver

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 9, 2023 License: Apache-2.0 Imports: 28 Imported by: 9

Documentation

Overview

Package driver provides access to the low level Tigris API. It abstracts underlying transport protocol.

Index

Examples

Constants

View Source
const (
	SetCookieHeaderKey = "Set-Cookie"
	CookieHeaderKey    = "Cookie"
)
View Source
const (
	GRPC  = "GRPC"
	HTTP  = "HTTP"
	HTTPS = "HTTPS"

	EnvClientID     = "TIGRIS_CLIENT_ID"
	EnvClientSecret = "TIGRIS_CLIENT_SECRET" //nolint:golint,gosec
	EnvToken        = "TIGRIS_TOKEN"         //nolint:golint,gosec
	EnvProtocol     = "TIGRIS_PROTOCOL"
	EnvURL          = "TIGRIS_URL"
	EnvProject      = "TIGRIS_PROJECT"
	EnvDBBranch     = "TIGRIS_DB_BRANCH"

	ClientVersion = "v1.0.0"
	UserAgent     = "tigris-client-go/" + ClientVersion
)
View Source
const (
	DefaultGRPCPort = 443
)

Variables

View Source
var (
	DefaultProtocol string
	DefaultURL      = "api.preview.tigrisdata.cloud"

	// TokenURLOverride Only used in tests to point auth to proper HTTP port in GRPC tests.
	TokenURLOverride string

	HeaderSchemaVersionValue []string
)

Functions

func GRPCError

func GRPCError(err error) error

func JAM

func JAM(t *testing.T, expected []string) gomock.Matcher

JAM = JSON Array Matcher.

func JM

func JM(t *testing.T, expected string) gomock.Matcher

func PM

func PtrToInt32

func PtrToInt32(b *int32) int32

func PtrToInt64

func PtrToInt64(b *int64) int64

func PtrToString

func PtrToString(s *string) string

func SetSchemaVersion

func SetSchemaVersion(v int)

Types

type AppKey

type AppKey api.AppKey

type CRUDWithOptions

type CRUDWithOptions interface {
	// contains filtered or unexported methods
}

type Collation

type Collation api.Collation

type CollectionOptions

type CollectionOptions api.CollectionOptions

type CreateBranchResponse

type CreateBranchResponse api.CreateBranchResponse

type CreateCollectionOptions

type CreateCollectionOptions struct {
	OnlyCreate bool
}

type CreateOrUpdateCollectionsResponse

type CreateOrUpdateCollectionsResponse api.CreateOrUpdateCollectionsResponse

type CreateProjectOptions

type CreateProjectOptions struct{}

type CreateProjectResponse

type CreateProjectResponse api.CreateProjectResponse

type Database

type Database interface {
	// BeginTx starts new transaction
	BeginTx(ctx context.Context, options ...*TxOptions) (Tx, error)
	// Insert array of documents into specified database and collection.
	Insert(ctx context.Context, collection string, docs []Document,
		options ...*InsertOptions) (*InsertResponse, error)

	// Replace array of documents into specified database and collection
	// Creates document if it doesn't exist.
	Replace(ctx context.Context, collection string, docs []Document,
		options ...*ReplaceOptions) (*ReplaceResponse, error)

	// Read documents from the collection matching the specified filter.
	Read(ctx context.Context, collection string, filter Filter, fields Projection,
		options ...*ReadOptions) (Iterator, error)

	// Explain the query planner for a specified filter.
	Explain(ctx context.Context, collection string, filter Filter, fields Projection,
		options ...*ReadOptions) (*ExplainResponse, error)

	// Search for documents in the collection matching specified query
	Search(ctx context.Context, collection string, request *SearchRequest) (SearchResultIterator, error)

	// Update documents in the collection matching the specified filter.
	Update(ctx context.Context, collection string, filter Filter, fields Update,
		options ...*UpdateOptions) (*UpdateResponse, error)

	// Delete documents from the collection matching specified filter.
	Delete(ctx context.Context, collection string, filter Filter, options ...*DeleteOptions) (*DeleteResponse, error)

	Count(ctx context.Context, collection string, filter Filter) (int64, error)

	// CreateOrUpdateCollection either creates a collection or update the collection with the new schema
	// There are three categories of data types supported:
	//   Primitive: Strings, Numbers, Binary Data, Booleans, UUIDs, DateTime
	//   Complex: Arrays
	//   Objects: A container data type defined by the user that stores fields of primitive types,
	//   complex types as well as other Objects
	//
	//  The data types are derived from the types defined in the JSON schema specification
	//  with extensions that enable support for richer semantics.
	//  As an example, the string is defined like this,
	//   {
	//     "name": {
	//       "type": "string"
	//     }
	//   }
	// More detailed information here: https://docs.tigrisdata.com/datamodels/types
	CreateOrUpdateCollection(ctx context.Context, collection string, schema Schema,
		options ...*CreateCollectionOptions) error

	// CreateOrUpdateCollections creates batch of collections
	CreateOrUpdateCollections(ctx context.Context, schema []Schema, options ...*CreateCollectionOptions) (*CreateOrUpdateCollectionsResponse, error)

	// DropCollection deletes the collection and all documents it contains.
	DropCollection(ctx context.Context, collection string, options ...*CollectionOptions) error

	// DropAllCollections deletes all the collections and all documents it contains.
	DropAllCollections(ctx context.Context, options ...*CollectionOptions) error

	// ListCollections lists collections in the database.
	ListCollections(ctx context.Context, options ...*CollectionOptions) ([]string, error)

	// DescribeCollection returns metadata of the collection in the database
	DescribeCollection(ctx context.Context, collection string, options ...*DescribeCollectionOptions) (
		*DescribeCollectionResponse, error)

	// CreateBranch creates a branch of this database
	CreateBranch(ctx context.Context, name string) (*CreateBranchResponse, error)

	// DeleteBranch deletes a branch of this database, throws an error if "main" branch is being deleted
	DeleteBranch(ctx context.Context, name string) (*DeleteBranchResponse, error)
}

Database is the interface that encapsulates the CRUD portions of the transaction API.

type DeleteBranchResponse

type DeleteBranchResponse api.DeleteBranchResponse

type DeleteOptions

type DeleteOptions api.DeleteRequestOptions

type DeleteProjectOptions

type DeleteProjectOptions struct{}

type DeleteProjectResponse

type DeleteProjectResponse api.DeleteProjectResponse

type DeleteResponse

type DeleteResponse api.DeleteResponse

type DescribeCollectionOptions

type DescribeCollectionOptions struct {
	SchemaFormat string
}

type DescribeCollectionResponse

type DescribeCollectionResponse api.DescribeCollectionResponse

type DescribeDatabaseResponse

type DescribeDatabaseResponse api.DescribeDatabaseResponse

type DescribeProjectOptions

type DescribeProjectOptions struct {
	SchemaFormat string
}

type DocStatus

type DocStatus = api.DocStatus

type Document

type Document json.RawMessage

func ToDocument

func ToDocument(t *testing.T, doc interface{}) Document

type Driver

type Driver interface {
	// Info returns server information
	Info(ctx context.Context) (*InfoResponse, error)
	// Health returns server health
	Health(ctx context.Context) (*HealthResponse, error)

	// UseDatabase returns and interface for collections and documents management
	// of the database
	UseDatabase(project string) Database
	UseSearch(project string) SearchClient

	// CreateProject creates the project
	CreateProject(ctx context.Context, project string, options ...*CreateProjectOptions) (*CreateProjectResponse, error)

	// DescribeDatabase returns project description metadata
	DescribeDatabase(ctx context.Context, project string, options ...*DescribeProjectOptions) (*DescribeDatabaseResponse, error)

	// ListProjects returns all projects
	ListProjects(ctx context.Context) ([]string, error)

	// DeleteProject deletes the project
	DeleteProject(ctx context.Context, project string, options ...*DeleteProjectOptions) (*DeleteProjectResponse, error)

	// Close releases resources of the driver
	Close() error

	CreateAppKey(ctx context.Context, project string, name string, description string) (*AppKey, error)
	DeleteAppKey(ctx context.Context, project string, id string) error
	UpdateAppKey(ctx context.Context, project string, id string, name string, description string) (*AppKey, error)
	ListAppKeys(ctx context.Context, project string) ([]*AppKey, error)
	RotateAppKeySecret(ctx context.Context, project string, id string) (*AppKey, error)

	CreateGlobalAppKey(ctx context.Context, name string, description string) (*GlobalAppKey, error)
	DeleteGlobalAppKey(ctx context.Context, id string) error
	UpdateGlobalAppKey(ctx context.Context, id string, name string, description string) (*GlobalAppKey, error)
	ListGlobalAppKeys(ctx context.Context) ([]*GlobalAppKey, error)
	RotateGlobalAppKeySecret(ctx context.Context, id string) (*GlobalAppKey, error)
}

Driver implements Tigris API.

Example
ctx := context.TODO()

c, _ := NewDriver(ctx, &config.Driver{URL: "localhost"})

db := c.UseDatabase("db1")

_ = db.CreateOrUpdateCollection(ctx, "coll1",
	Schema(`{ "properties": { "F1": { "type": "string" }, "F2": { "type": "string" } }, "primary_key": ["F1"] }`))

_, _ = db.Insert(ctx, "c1", []Document{Document(`{"F1":"V1"}`)})

it, _ := db.Read(ctx, "c1", Filter(`{"F1":"V1"}`), Projection(`{}`))

var doc Document
for it.Next(&doc) {
	fmt.Printf("doc: %v\n", doc)
}

_ = it.Err()

_, _ = db.Delete(ctx, "c1", Filter(`{"F1":"V1"}`))

tx, _ := c.UseDatabase("db1").BeginTx(ctx)
defer func() { _ = tx.Rollback(ctx) }()

_, _ = tx.Insert(ctx, "c1", []Document{Document(`{"F1":"V1"}`)})

it, _ = tx.Read(ctx, "c1", Filter(`{"F1":"V1"}`), Projection("{}"))

for it.Next(&doc) {
	fmt.Printf("doc: %v\n", doc)
}

var e Error

err := it.Err()
if errors.As(err, &e) && e.Code == api.Code_ALREADY_EXISTS {
	// handle already exists error
}

_, _ = tx.Update(ctx, "c1", Filter(`{"F1":"V1"}`),
	Update(`{"$set" : { "F2" : "V2"}}`), &UpdateOptions{})

_, _ = tx.Delete(ctx, "c1", Filter(`{"F1":"V1"}`), &DeleteOptions{})

_ = tx.Commit(ctx)
Output:

func NewDriver

func NewDriver(ctx context.Context, cfg *config.Driver) (Driver, error)

NewDriver connect to the Tigris instance at the specified URL. URL should be in the form: {hostname}:{port}.

type Error

type Error struct {
	*api.TigrisError
}

func NewError

func NewError(c api.Code, format string, a ...interface{}) *Error

func (*Error) As

func (e *Error) As(i any) bool

As converts driver.Error the error which implements AsTigrisError interface.

type ExplainResponse

type ExplainResponse api.ExplainResponse

type Facet

type Facet json.RawMessage

type Filter

type Filter json.RawMessage

type GlobalAppKey

type GlobalAppKey api.GlobalAppKey

type HealthResponse

type HealthResponse api.HealthCheckResponse

type IndexInfo

type IndexInfo = api.IndexInfo

type IndexSource

type IndexSource = api.IndexSource

type InfoResponse

type InfoResponse api.GetInfoResponse

type InsertOptions

type InsertOptions api.InsertRequestOptions

type InsertResponse

type InsertResponse api.InsertResponse

type Invitation

type Invitation api.Invitation

type InvitationInfo

type InvitationInfo api.InvitationInfo

type Iterator

type Iterator interface {
	Next(d *Document) bool
	Err() error
	Close()
}

type JSONArrMatcher

type JSONArrMatcher struct {
	T        *testing.T
	Expected []string
}

func (*JSONArrMatcher) Got

func (matcher *JSONArrMatcher) Got(actual any) string

func (*JSONArrMatcher) Matches

func (matcher *JSONArrMatcher) Matches(actual any) bool

func (*JSONArrMatcher) String

func (matcher *JSONArrMatcher) String() string

type JSONMatcher

type JSONMatcher struct {
	T        *testing.T
	Expected []byte
}

func (*JSONMatcher) Got

func (matcher *JSONMatcher) Got(actual interface{}) string

func (*JSONMatcher) Matches

func (matcher *JSONMatcher) Matches(actual interface{}) bool

func (*JSONMatcher) String

func (matcher *JSONMatcher) String() string

type ListProjectsResponse

type ListProjectsResponse api.ListProjectsResponse

type Management

type Management interface {
	GetAccessToken(ctx context.Context, clientID string, clientSecret string, refreshToken string) (*TokenResponse, error)

	CreateNamespace(ctx context.Context, name string) error
	ListNamespaces(ctx context.Context) ([]*Namespace, error)

	CreateInvitations(ctx context.Context, invitations []*InvitationInfo) error
	DeleteInvitations(ctx context.Context, email string, status string) error
	ListInvitations(ctx context.Context, status string) ([]*Invitation, error)
	VerifyInvitation(ctx context.Context, email string, code string) error
	ListUsers(ctx context.Context) ([]*User, error)

	Close() error
}

Management declares Tigris Management APIs.

func NewManagement

func NewManagement(ctx context.Context, cfg *config.Driver) (Management, error)

NewManagement instantiates authentication API client.

type Message

type Message json.RawMessage

type Namespace

type Namespace api.NamespaceInfo

type Observability

type Observability interface {
	QuotaLimits(ctx context.Context) (*QuotaLimits, error)
	QuotaUsage(ctx context.Context) (*QuotaUsage, error)

	Close() error
}

Observability declares Tigris Observability APIs.

func NewObservability

func NewObservability(ctx context.Context, cfg *config.Driver) (Observability, error)

NewObservability instantiates observability API client.

type Projection

type Projection json.RawMessage

type ProtoMatcher

type ProtoMatcher struct {
	Message proto.Message
}

func (*ProtoMatcher) Matches

func (matcher *ProtoMatcher) Matches(actual interface{}) bool

func (*ProtoMatcher) String

func (matcher *ProtoMatcher) String() string

type QuotaLimits

type QuotaLimits api.QuotaLimitsResponse

type QuotaUsage

type QuotaUsage api.QuotaUsageResponse

type ReadOptions

type ReadOptions struct {
	// Limit the number of documents returned by the read operation.
	Limit int64
	// Number of documents to skip before starting to return resulting documents.
	Skip int64
	// A cursor for use in pagination. The next streams will return documents after this offset.
	Offset []byte
	// Collation allows you to specify string comparison rules. Default is case-sensitive.
	Collation *api.Collation
	// Sort order
	Sort []byte
}

type ReplaceOptions

type ReplaceOptions api.ReplaceRequestOptions

type ReplaceResponse

type ReplaceResponse api.ReplaceResponse

type Schema

type Schema json.RawMessage

type SearchClient

type SearchClient interface {
	CreateOrUpdateIndex(ctx context.Context, name string, schema Schema) error
	GetIndex(ctx context.Context, name string) (*IndexInfo, error)
	DeleteIndex(ctx context.Context, name string) error
	ListIndexes(ctx context.Context, filter *IndexSource) ([]*IndexInfo, error)
	Get(ctx context.Context, name string, ids []string) ([]*SearchHit, error)
	CreateByID(ctx context.Context, name string, id string, doc Document) error
	Create(ctx context.Context, name string, docs []Document) ([]*DocStatus, error)
	CreateOrReplace(ctx context.Context, name string, docs []Document) ([]*DocStatus, error)
	Update(ctx context.Context, name string, docs []Document) ([]*DocStatus, error)
	Delete(ctx context.Context, name string, ids []string) ([]*DocStatus, error)
	DeleteByQuery(ctx context.Context, name string, filter Filter) (int32, error)
	Search(ctx context.Context, name string, req *SearchRequest) (SearchIndexResultIterator, error)
}

func NewGRPCSearchClient

func NewGRPCSearchClient(project string, client api.SearchClient) SearchClient

type SearchHit

type SearchHit = api.SearchHit

type SearchIndexResponse

type SearchIndexResponse = *api.SearchIndexResponse

type SearchIndexResultIterator

type SearchIndexResultIterator interface {
	Next(r *SearchIndexResponse) bool
	Err() error
	Close()
}

type SearchRequest

type SearchRequest struct {
	Q             string
	SearchFields  []string
	Filter        Filter
	Facet         Facet
	Sort          SortOrder
	IncludeFields []string
	ExcludeFields []string
	Page          int32
	PageSize      int32
	Collation     *Collation
	Vector        Vector
}

type SearchResponse

type SearchResponse *api.SearchResponse

type SearchResultIterator

type SearchResultIterator interface {
	Next(r *SearchResponse) bool
	Err() error
	Close()
}

type SortOrder

type SortOrder []json.RawMessage

type TokenResponse

type TokenResponse api.GetAccessTokenResponse

type Tx

type Tx interface {
	// Commit all the modification of the transaction
	Commit(ctx context.Context) error

	// Rollback discard all the modification made by the transaction
	Rollback(ctx context.Context) error

	Database
}

Tx object is used to atomically modify documents. This object is returned by BeginTx.

type TxOptions

type TxOptions api.TransactionOptions

type Update

type Update json.RawMessage

type UpdateOptions

type UpdateOptions api.UpdateRequestOptions

type UpdateResponse

type UpdateResponse api.UpdateResponse

type User

type User api.User

type Vector

type Vector json.RawMessage

type WriteOptions

type WriteOptions api.WriteOptions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL