persistence

Documentation

Overview

Copyright 2023 The Simila Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• func CleanName(name string) (string, error)
• func ConcatPath(p1, p2 string) string
• func Count(ctx context.Context, q sqlx.QueryerContext, query string, params ...any) (int64, error)
• func MapError(err error) error
• func MapKeywordsToListFn(startMark, endMark string) func(item SearchQueryResultItem) SearchQueryResultItem
• func Path(names []string) string
• func Scan[T any](rows *sqlx.Rows) (T, error)
• func ScanRows[T any](rows *sqlx.Rows) ([]T, error)
• func ScanRowsQueryResult[T any](rows *sqlx.Rows) ([]T, error)
• func ScanRowsQueryResultAndMap[T, K any](rows *sqlx.Rows, mapFn func(entity T) K) ([]K, error)
• func SplitPath(path string) []string
• func ToNodePath(path string) string
• func ToNodePathName(path string) (string, string)
• type Db
• type DbConfig
  • func (ds DbConfig) DataSourceFull() string
  • func (ds DbConfig) DataSourceNoDb() string
• type DbContainer
  • func NewNilDbContainer(opts ...DbOption) (DbContainer, error)
  • func NewPgDbContainer(ctx context.Context, image string, opts ...DbOption) (DbContainer, error)
• type DbOption
  • func WithDbName(dbName string) DbOption
  • func WithHost(host string) DbOption
  • func WithPassword(password string) DbOption
  • func WithPort(port string) DbOption
  • func WithSslMode(sslMode string) DbOption
  • func WithUser(user string) DbOption
• type DeleteNodesQuery
• type Format
• type IndexRecord
• type IndexRecordQuery
• type ListNodesQuery
• type ModelTx
• type Node
• type QueryResult
• type SearchQuery
• type SearchQueryResult
• type SearchQueryResultItem
• type Tags
  • func (t Tags) JSON() string
  • func (t *Tags) Scan(value any) error
  • func (t Tags) Value() (value driver.Value, err error)
• type Tx

Constants

const (
	PqForeignKeyViolationError = pq.ErrorCode("23503")
	PqUniqueViolationError     = pq.ErrorCode("23505")
)

const (
	NodeFlagFolder   = 0
	NodeFlagDocument = 1 // if it is set, it is a document. If not set, it is a folder
)

Functions

func CleanName

func CleanName(name string) (string, error)

CleanName checks whether the name contains '/' and trims spaces if needed. It returns the modified name or an error if any

func ConcatPath

func ConcatPath(p1, p2 string) string

ConcatPath allows to concat two paths

func Count

func Count(ctx context.Context, q sqlx.QueryerContext, query string, params ...any) (int64, error)

func MapError

func MapError(err error) error

func MapKeywordsToListFn

func MapKeywordsToListFn(startMark, endMark string) func(item SearchQueryResultItem) SearchQueryResultItem

func Path

func Path(names []string) string

Path composes the path from the names

func Scan

func Scan[T any](rows *sqlx.Rows) (T, error)

func ScanRows

func ScanRows[T any](rows *sqlx.Rows) ([]T, error)

func ScanRowsQueryResult

func ScanRowsQueryResult[T any](rows *sqlx.Rows) ([]T, error)

func ScanRowsQueryResultAndMap

func ScanRowsQueryResultAndMap[T, K any](rows *sqlx.Rows, mapFn func(entity T) K) ([]K, error)

func SplitPath

func SplitPath(path string) []string

SplitPath splits the path on the nodes name according to their levels: "/aaa" -> "aaa" "aaa" -> "aaa" "///aaa//bbb" -> "aaa", "bbb" "aaa//bbb/c" -> "aaa", "bbb", "c"

func ToNodePath

func ToNodePath(path string) string

ToNodePath returns the path in a form as expected by Node

func ToNodePathName

func ToNodePathName(path string) (string, string)

ToNodePathName returns the path and name parts of the given path as expected by Node

Types

type Db

type Db interface {
	// NewModelTx creates new ModelTx object
	NewModelTx(ctx context.Context) ModelTx
	// NewTx creates Tx object
	NewTx(ctx context.Context) Tx
}

Db interface exposes

type DbConfig

type DbConfig struct {
	Host     string
	Port     string
	User     string
	Password string
	DbName   string
	SslMode  string
}

func (DbConfig) DataSourceFull

func (ds DbConfig) DataSourceFull() string

func (DbConfig) DataSourceNoDb

func (ds DbConfig) DataSourceNoDb() string

type DbContainer

type DbContainer interface {
	io.Closer
	DbConfig() DbConfig
}

func NewNilDbContainer

func NewNilDbContainer(opts ...DbOption) (DbContainer, error)

func NewPgDbContainer

func NewPgDbContainer(ctx context.Context, image string, opts ...DbOption) (DbContainer, error)

NewPgDbContainer runs pg database in a docker container.

type DbOption

type DbOption func(cfg *DbConfig)

func WithDbName

func WithDbName(dbName string) DbOption

func WithHost

func WithHost(host string) DbOption

func WithPassword

func WithPassword(password string) DbOption

func WithPort

func WithPort(port string) DbOption

func WithSslMode

func WithSslMode(sslMode string) DbOption

func WithUser

func WithUser(user string) DbOption

type DeleteNodesQuery

type DeleteNodesQuery struct {
	// FilterConditions contains the node selection filter
	FilterConditions string
	// Force flag allows to delete children for the selected folders. For example, if
	// the selected node is a folder, and it has children, that don't match the filter criteria,
	// they also will be deleted if the force is true.
	Force bool
}

DeleteNodesQuery provides parameters for deleting multiple nodes

type Format

type Format struct {
	ID        string    `db:"id"`
	Basis     []byte    `db:"basis"`
	CreatedAt time.Time `db:"created_at"`
	UpdatedAt time.Time `db:"updated_at"`
}

type IndexRecord

type IndexRecord struct {
	ID        string    `db:"id"`
	NodeID    int64     `db:"node_id"`
	Segment   string    `db:"segment"`
	Vector    []byte    `db:"vector"`
	Format    string    `db:"format"`
	RankMult  float64   `db:"rank_multiplier"`
	CreatedAt time.Time `db:"created_at"`
	UpdatedAt time.Time `db:"updated_at"`

	// search module specific fields
	SegmentTsVector string `db:"segment_tsvector"`
}

type IndexRecordQuery

type IndexRecordQuery struct {
	// Format is filter records by the format. If empty no format filter
	Format string
	// NodeID sets the ID of the node
	NodeID        int64
	CreatedAfter  time.Time
	CreatedBefore time.Time
	FromID        string
	Limit         int
}

type ListNodesQuery

type ListNodesQuery struct {
	// FilterConditions contains the node selection filter
	FilterConditions string
	Offset           int64
	Limit            int64
}

ListNodesQuery allows to select nodes by the condition provided

type ModelTx

type ModelTx interface {
	Tx

	// CreateFormat creates format entry
	CreateFormat(format Format) (Format, error)
	// GetFormat retrieves format entry by ID
	GetFormat(ID string) (Format, error)
	// DeleteFormat deletes format entry by ID (only if not referenced)
	DeleteFormat(ID string) error
	// ListFormats lists all the existing format entries
	ListFormats() ([]Format, error)

	// CreateNodes allows to create one or several new Nodes. If a Node with the path already exists,
	// the function will return ErrExists.
	CreateNodes(nodes ...Node) ([]Node, error)
	// ListAllNodesByPath returns all nodes for the path. For example for the path="/a/b/doc.txt"
	// the result nodes will be {<"/", "a">, {<"/a/", "b">, <"/a/b/", "doc.txt">}
	ListAllNodesByPath(path string) ([]Node, error)
	// ListNodes returns the nodes according to the query filter request
	ListNodes(query ListNodesQuery) ([]Node, error)

	// GetNode returns the node by its fqnp
	GetNode(fqnp string) (Node, error)
	// UpdateNode updates node data
	UpdateNode(node Node) error

	// DeleteNodes deletes the Nodes that matches to the DeleteNodesQuery and all the records associated with the nodes.
	// force allows to delete folder nodes with children. If the node is a folder, and there are children,
	// but the force flag is false, the function will return ErrConflict error
	//
	// NOTE: The operation is not atomic until an external transaction is not started,
	// the caller MUST start the transaction before using this method.
	DeleteNodes(DeleteNodesQuery) error

	// UpsertIndexRecords creates or updates index record entries. It returns the new records created
	UpsertIndexRecords(records ...IndexRecord) (int64, error)
	// DeleteIndexRecords deletes index record entries
	DeleteIndexRecords(records ...IndexRecord) (int64, error)
	// QueryIndexRecords lists query matching index record entries
	QueryIndexRecords(query IndexRecordQuery) (QueryResult[IndexRecord, string], error)

	// Search performs search across existing index records
	// the query string should be formed in accordance with the query
	// language of the underlying search engine
	//
	// NOTE: The operation is not atomic until an external transaction is not started,
	// the caller MUST start the transaction before using this method.
	Search(query SearchQuery) (SearchQueryResult, error)
}

ModelTx provides a transaction with some methods for accessing to the Model objects

type Node

type Node struct {
	ID   int64  `db:"id"`
	Path string `db:"path"`
	// Name is either name of the folder or a document
	Name      string    `db:"name"`
	Tags      Tags      `db:"tags"`
	Flags     int32     `db:"flags"`
	CreatedAt time.Time `db:"created_at"`
	UpdatedAt time.Time `db:"updated_at"`
}

Node describes an object. The node has Path and Name, and the pair <Path, Name> must be unique within the tree. Name cannot be empty.

Root path is "/". The 3rd level path, for example, could be "/aaa/bbb/ccc/". Path is always ends by "/"

type QueryResult

type QueryResult[T any, N any] struct {
	Items  []T
	NextID N
	Total  int64
}

type SearchQuery

type SearchQuery struct {
	TextQuery        string
	FilterConditions string
	GroupByPathOff   bool // GroupByPathOff turns off results grouping by path.
	Offset           int
	Limit            int
}

type SearchQueryResult

type SearchQueryResult struct {
	Items []SearchQueryResultItem
	Total int64
}

type SearchQueryResultItem

type SearchQueryResultItem struct {
	IndexRecord
	Path                string   `db:"path"`
	MatchedKeywordsList []string // mapped manually after filling the MatchedKeywords
	MatchedKeywords     string   `db:"matched_keywords"`
	Score               float32  `db:"score"`
}

type Tags

type Tags map[string]string

func (Tags) JSON

func (t Tags) JSON() string

func (*Tags) Scan

func (t *Tags) Scan(value any) error

func (Tags) Value

func (t Tags) Value() (value driver.Value, err error)

type Tx

type Tx interface {
	// MustBegin starts the transaction
	MustBegin()
	// MustBeginSerializable starts new transaction with Serializable isolation level
	MustBeginSerializable()
	// Commit commits the changes made within the transaction
	Commit() error
	// Rollback rolls the transaction back
	Rollback() error
	// ExecScript allows to execute the sql statements from the file provided
	ExecScript(sqlScript string) error
}

Tx interface describes an abstract DB transaction.