tigergraph

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2023 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Copyright 2023 Adarga Limited

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: https://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.

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: https://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.

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: https://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.

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: https://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.

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: https://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.

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: https://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.

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: https://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.

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: https://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.

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: https://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

View Source 
const (
	// PingURL is the URL to make a ping request
	PingURL = "/api/ping"

	// TigerGraphDateTimeFormat is the date format used by TigerGraph
	TigerGraphDateTimeFormat = "2006-01-02 15:04:05"
)
View Source 
const (
	// MetadataGraphName is the name of the graph the client stores metadata in
	MetadataGraphName = "ClientMetadata"

	// ExpectedFailurePrefix is the start of the error received when the client has not initialised the metadata
	ExpectedFailurePrefix = "Graph name " + MetadataGraphName + " cannot be found."
)
View Source 
const (
	// FileURL is the tiger graph URL to run arbitrary GSQL
	FileURL = "/gsqlserver/gsql/file"

	// SuccessString is the string we expect to find in the response that indicates successful return
	SuccessString = "__GSQL__RETURN__CODE__,0"

	// SemanticFailureString is the string to look for which indicates that some error in semantics
	// occurred when running the GSQL
	SemanticFailureString = "Semantic Check Fails:"
)
View Source 
const GetCurrentMigrationVersionURL = "/query/get_latest_migration"

GetCurrentMigrationVersionURL is the URL to get the current migration version

View Source 
const GetGraphMetadataQueryURL = "/gsqlserver/gsql/schema"

GetGraphMetadataQueryURL is the TigerGraph URL to get schema metadata

View Source 
const RequestTokenURL = "/requesttoken"

RequestTokenURL is the URL part for getting a token from TigerGraph

View Source 
const UpsertURL = "/graph"

UpsertURL defines the tigergraph query endpoint for upserting data. It must be appended by the graph name

Variables

View Source 
var (
	// ErrPost represents a failure to make a POST request
	ErrPost = errors.New("failed to make POST request to TigerGraph")

	// ErrGet represents a failure to make a GET request
	ErrGet = errors.New("failed to make GET request to TigerGraph")

	// ErrNonOK represents a non-OK status code (200) was returned
	ErrNonOK = errors.New("TigerGraph returned non-OK status code")

	// ErrBodyReadFailed  represents a failure to read the TigerGraph response body
	ErrBodyReadFailed = errors.New("failed to read response body")

	// ErrTigerGraphError means that an error is present on the returned response body
	ErrTigerGraphError = errors.New("error in the response body")

	// ErrRequestFailed represents a failure to make a request to TigerGraph
	ErrRequestFailed = errors.New("failed request")

	// ErrNotOneResult represents a response shape that does not contain exactly one result
	ErrNotOneResult = errors.New("TigerGraph did not respond with exactly one result")
)
View Source 
var (
	// ErrUnknownInitialisationCheckFailure occurs when an error is returned, but it is not the
	// error which signals that initialisation hasn't happened yet
	ErrUnknownInitialisationCheckFailure = errors.New("initialisation check failed for an unknown reason")

	// ErrTigerGraphSchemaSetUpFailed means that a failure occurred when running migrations
	ErrTigerGraphSchemaSetUpFailed = errors.New("failed to set up schema in tiger graph")

	// ErrInvalidMigrationNumber means that a supplied migration number was invalid
	ErrInvalidMigrationNumber = errors.New("migration number was invalid")
)
View Source 
var (
	// ErrMarshallingJSONL represents failure to turn the supplied argument into JSONL
	ErrMarshallingJSONL = errors.New("failed to marshal into JSONL")

	// ErrLoadingJobRequestFailed represents failure to make a request to TigerGraph
	ErrLoadingJobRequestFailed = errors.New("failed to make request to loading job endpoint")

	// ErrLoadingJobPartialFailure represents a failed request that nevertheless made some successful changes
	ErrLoadingJobPartialFailure = errors.New("not all lines of the JSONL were saved successfully")
)
View Source 
var (
	// ErrGSQLFailure is an error in the case of being unable to run GSQL on the TG server
	ErrGSQLFailure = errors.New("failed to execute GSQL")
)
View Source 
var InitFileString string

InitFileString is the content of the initialisation GSQL as a string

Functions

This section is empty.

Types

type CurrentMigrationVersionPostBody 

type CurrentMigrationVersionPostBody struct {
	GraphName string `json:"graph_name"`
}

CurrentMigrationVersionPostBody is the request shape sent to TG to get the migration version

type CurrentMigrationVersionResponse 

type CurrentMigrationVersionResponse struct {
	Version *Version                                `json:"version"`
	Error   bool                                    `json:"error"`
	Message string                                  `json:"message"`
	Results []CurrentMigrationVersionResponseResult `json:"results"`
}

CurrentMigrationVersionResponse is the response from TG containing the migration version

type CurrentMigrationVersionResponseResult 

type CurrentMigrationVersionResponseResult struct {
	LatestMigration []MigrationVertex `json:"latest_migration"`
}

CurrentMigrationVersionResponseResult is the result shape inside the response

type GraphMetadataAttribute 

type GraphMetadataAttribute struct {
	AttributeName string                     `json:"AttributeName"`
	AttributeType GraphMetadataAttributeType `json:"AttributeType"`
}

GraphMetadataAttribute is the attribute on a vertex type

type GraphMetadataAttributeType 

type GraphMetadataAttributeType struct {
	Name string `json:"Name"`
}

GraphMetadataAttributeType is the type attribute on a vertex type attribute

type GraphMetadataEdgePair 

type GraphMetadataEdgePair struct {
	From string `json:"From"`
	To   string `json:"To"`
}

GraphMetadataEdgePair is an edge pair

type GraphMetadataEdgeType 

type GraphMetadataEdgeType struct {
	IsDirected         bool                     `json:"IsDirected"`
	ToVertexTypeName   string                   `json:"ToVertexTypeName"`
	Config             map[string]string        `json:"Config"`
	IsLocal            bool                     `json:"IsLocal"`
	Attributes         []GraphMetadataAttribute `json:"Attributes"`
	FromVertexTypeName string                   `json:"FromVertexTypeName"`
	EdgePairs          []GraphMetadataEdgePair  `json:"EdgePairs"`
	Name               string                   `json:"Name"`
}

GraphMetadataEdgeType is an edge type in the metadata response body

type GraphMetadataPartialResponse 

type GraphMetadataPartialResponse struct {
	Message string          `json:"message"`
	Error   bool            `json:"error"`
	Results json.RawMessage `json:"results"`
}

GraphMetadataPartialResponse does not specify a type for the "results" key, because we do not yet know the type when we first get the response (until we check the error status).

type GraphMetadataResponse 

type GraphMetadataResponse struct {
	Message string                       `json:"message"`
	Error   bool                         `json:"error"`
	Results *GraphMetadataResponseResult `json:"results"`
}

GraphMetadataResponse is the whole TigerGraph response for a metadata query

type GraphMetadataResponseResult 

type GraphMetadataResponseResult struct {
	GraphName   string                    `json:"GraphName"`
	VertexTypes []GraphMetadataVertexType `json:"VertexTypes"`
	EdgeTypes   []GraphMetadataEdgeType   `json:"EdgeTypes"`
}

GraphMetadataResponseResult is the result shape contained in the response when getting the graph metadata

type GraphMetadataVertexType 

type GraphMetadataVertexType struct {
	Config     map[string]string                `json:"Config"`
	IsLocal    bool                             `json:"IsLocal"`
	Attributes []GraphMetadataAttribute         `json:"Attributes"`
	PrimaryID  GraphMetadataVertexTypePrimaryID `json:"PrimaryId"`
	Name       string                           `json:"Name"`
}

GraphMetadataVertexType is a vertex type in the metadata response body

type GraphMetadataVertexTypePrimaryID 

type GraphMetadataVertexTypePrimaryID struct {
	AttributeType        GraphMetadataAttributeType `json:"AttributeType"`
	PrimaryIDAsAttribute bool                       `json:"PrimaryIdAsAttribute"`
	AttributeName        string                     `json:"AttributeName"`
}

GraphMetadataVertexTypePrimaryID is the primary ID attribute in a vertex type

type LoadingJobObjectResult 

type LoadingJobObjectResult struct {
	TypeName                   string `json:"typeName"`
	ValidObject                int    `json:"validObject"`
	NoIDFound                  int    `json:"noIdFound"`
	InvalidAttribute           int    `json:"invalidAttribute"`
	InvalidVertexType          int    `json:"invalidVertexType"`
	InvalidPrimaryID           int    `json:"invalidPrimaryId"`
	InvalidSecondaryID         int    `json:"invalidSecondaryId"`
	IncorrectFixedBinaryLength int    `json:"incorrectFixedBinaryLength"`
}

LoadingJobObjectResult is the shape of an edge or vertex entry in the statistics shape

type LoadingJobResponse 

type LoadingJobResponse struct {
	Version struct {
		Edition string `json:"edition"`
		API     string `json:"api"`
		Schema  int    `json:"schema"`
	} `json:"version"`
	Error   bool                       `json:"error"`
	Message string                     `json:"message"`
	Results []LoadingJobResponseResult `json:"results"`
	Code    string                     `json:"code"`
}

LoadingJobResponse is the shape of the response body when saving a loading job

type LoadingJobResponseResult 

type LoadingJobResponseResult struct {
	SourceFileName string               `json:"sourceFileName"`
	Statistics     LoadingJobStatistics `json:"statistics"`
}

LoadingJobResponseResult is the shape of the results value in the response body when saving a loading job, edge or vertex

type LoadingJobStatistics 

type LoadingJobStatistics struct {
	ValidLine           int                      `json:"validLine"`
	RejectLine          int                      `json:"rejectLine"`
	FailedConditionLine int                      `json:"failedConditionLine"`
	NotEnoughToken      int                      `json:"notEnoughToken"`
	InvalidJSON         int                      `json:"invalidJson"`
	OversizeToken       int                      `json:"oversizeToken"`
	Vertex              []LoadingJobObjectResult `json:"vertex"`
	Edge                []LoadingJobObjectResult `json:"edge"`
}

LoadingJobStatistics is the shape of statistics from the returned loading job results

type MigrationUpsertPayload 

type MigrationUpsertPayload struct {
	Vertices MigrationVerticesPayload `json:"vertices"`
}

MigrationUpsertPayload is the whole payload sent to the upsert vertices endpoint for migrations

type MigrationVertex 

type MigrationVertex struct {
	Attributes MigrationVertexAttributes `json:"attributes"`
	VID        string                    `json:"v_id"`
	VType      string                    `json:"v_type"`
}

MigrationVertex is the shape of a returned migration vertex

type MigrationVertexAttributes 

type MigrationVertexAttributes struct {
	CreatedAt       string `json:"created_at"`
	MigrationNumber string `json:"migration_number"`
	Mode            string `json:"mode"`
	GraphName       string `json:"graph_name"`
}

MigrationVertexAttributes is the attributes of a migration vertex

type MigrationVertexPayload 

type MigrationVertexPayload struct {
	GraphName       MigrationVertexPayloadValue[string]    `json:"graph_name"`
	MigrationNumber MigrationVertexPayloadValue[string]    `json:"migration_number"`
	Mode            MigrationVertexPayloadValue[string]    `json:"mode"`
	CreatedAt       MigrationVertexPayloadValue[time.Time] `json:"created_at"`
}

MigrationVertexPayload is the shape of a migration vertex being stored in the vertex upsert payload

type MigrationVertexPayloadValue 

type MigrationVertexPayloadValue[T any] struct {
	Value T `json:"value"`
}

MigrationVertexPayloadValue is an object containing a "value" attribute

type MigrationVerticesPayload 

type MigrationVerticesPayload struct {
	Migration map[string]MigrationVertexPayload `json:"Migration"`
}

MigrationVerticesPayload is the map to all vertices in the payload

type RequestTokenRequest 

type RequestTokenRequest struct {
	Graph string `json:"graph"`
}

RequestTokenRequest is the shape of the request to the TigerGraph endpoint for fetching a token

type RequestTokenResponse 

type RequestTokenResponse struct {
	Code                        string                      `json:"code"`
	ExpirationSecondsSinceEpoch int64                       `json:"expiration"`
	Error                       bool                        `json:"error"`
	Message                     string                      `json:"message"`
	Results                     RequestTokenResponseResults `json:"results"`
}

RequestTokenResponse represents the response body from TigerGraph when requesting a token

type RequestTokenResponseResults 

type RequestTokenResponseResults struct {
	Token string `json:"token"`
}

RequestTokenResponseResults represents the token results shape

type ResponseVertex 

type ResponseVertex[T any] struct {
	VID        string `json:"v_id"`
	VType      string `json:"v_type"`
	Attributes T      `json:"attributes"`
}

type TigerGraphClient 

type TigerGraphClient struct {
	BaseURL           string
	BaseFileURL       string
	BasicAuthUsername string
	BasicAuthPassword string
	Tokens            map[string]*Token
}

TigerGraphClient provides an idiomatic interface to TigerGraph

func NewClient 

func NewClient(
	baseURL string,
	baseFileURL string,
	username string,
	password string,
) *TigerGraphClient

NewClient creates a new TigerGraphClient

func (*TigerGraphClient) ApplyBasicAuth 

func (c *TigerGraphClient) ApplyBasicAuth(req *http.Request)

ApplyBasicAuth takes a request and authenticates it generally as a TigerGraph user for GSQL server requests

https://docs.tigergraph.com/tigergraph-server/current/api/authentication#_gsql_server_requests

func (*TigerGraphClient) ApplyTokenAuth 

func (c *TigerGraphClient) ApplyTokenAuth(req *http.Request, graph string) error

ApplyTokenAuth takes a request and authenticates it for a specified graph, using TigerGraph's RESTPP token authentication endpoint.

https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_request_a_token

func (*TigerGraphClient) Auth 

func (c *TigerGraphClient) Auth(ctx context.Context, graph string) error

Auth authenticates with TigerGraph by hitting the auth endpoint using Basic Auth. Will do nothing if a non-expired token for the requested graph already exists in the client cache.

func (*TigerGraphClient) CheckIsInitialised 

func (c *TigerGraphClient) CheckIsInitialised(ctx context.Context) (bool, error)

CheckIsInitialised determines if the metadata graph has been initialised and ready for use.

func (*TigerGraphClient) CreateGSQLServerRequest 

func (c *TigerGraphClient) CreateGSQLServerRequest(ctx context.Context, method string, url string, body string) (*http.Request, error)

CreateGSQLServerRequest returns a Request instance that is authenticated and ready to pass to RequestInto. This is useful if headers need to be changed by the caller (such as setting the Content-Type).

func (*TigerGraphClient) Get 

func (c *TigerGraphClient) Get(ctx context.Context, queryURL string, graph string, result interface{}) error

Get makes a GET request to the TigerGraph endpoint. This handles auth automatically.

func (*TigerGraphClient) GetCurrentMigrationNumber 

func (c *TigerGraphClient) GetCurrentMigrationNumber(ctx context.Context, graph string) (string, error)

GetCurrentMigrationNumber returns the current migration number set on the TG instance. Returns "" if no migrations have been run

func (*TigerGraphClient) GetGraphMetadata 

func (c *TigerGraphClient) GetGraphMetadata(ctx context.Context, graphName string) (*GraphMetadataResponse, error)

GetGraphMetadata returns the graph metadata for a given graph name

func (*TigerGraphClient) Migrate 

func (c *TigerGraphClient) Migrate(
	ctx context.Context,
	graph string,
	version string,
	initVersion string,
	migrationFileDir string,
	dryRun bool,
) error

Migrate checks the status of migrations in the metadata graph and uses that information along with the specified version to determine which migrations to run.

If the metadata graph does not yet exist, it is created and initialised.

func (*TigerGraphClient) Post 

func (c *TigerGraphClient) Post(ctx context.Context, queryURL string, graph string, body interface{}, result interface{}) error

Post makes a POST request to the TigerGraph endpoint. This handles auth automatically.

func (*TigerGraphClient) PostRaw 

func (c *TigerGraphClient) PostRaw(ctx context.Context, queryURL string, graph string, body []byte, result interface{}) error

PostRaw makes a POST request to the TigerGraph endpoint with some given bytes. This handles auth automatically.

func (*TigerGraphClient) RequestInto 

func (c *TigerGraphClient) RequestInto(req *http.Request, result interface{}) error

RequestInto takes an HTTP request, performs it and unmarshals the response into the supplied result argument.

func (*TigerGraphClient) RunGSQL 

func (c *TigerGraphClient) RunGSQL(ctx context.Context, body string) error

RunGSQL executes arbitrary GSQL on a remote TG instance using the client. If any failure is detected, an error is returned. Note however that this does not mean that none of the GSQL was executed. You may need to inspect the logged response to identify what succeeded in the request.

func (*TigerGraphClient) RunLoadingJobJSONL 

func (c *TigerGraphClient) RunLoadingJobJSONL(ctx context.Context,
	graphName string,
	loadingJobName string,
	lines []any,
) error

RunLoadingJobJSONL runs a loading job with the given array of interfaces.

func (*TigerGraphClient) Upsert 

func (c *TigerGraphClient) Upsert(ctx context.Context, graphName string, data any) (*UpsertResponseResult, error)

Upsert upserts data to the given graph. https://docs.tigergraph.com/tigergraph-server/current/api/upsert-rest#_examples

type TigerGraphResponse 

type TigerGraphResponse[T any] struct {
	Version Version `json:"version"`
	Message string  `json:"message"`
	Error   bool    `json:"error"`
	Results []T     `json:"results"`
}

type Token 

type Token struct {
	Value   string
	Expires time.Time
}

Token is used to track active TigerGraph tokens on the client

type UpsertResponse 

type UpsertResponse struct {
	Version *Version               `json:"version"`
	Error   bool                   `json:"error"`
	Message string                 `json:"message"`
	Results []UpsertResponseResult `json:"results"`
}

UpsertResponse is the full response from TigerGraph

type UpsertResponseResult 

type UpsertResponseResult struct {
	AcceptedVertices     int            `json:"accepted_vertices"`
	AcceptedEdges        int            `json:"accepted_edges"`
	SkippedVertices      int            `json:"skipped_vertices"`
	SkippedEdges         int            `json:"skipped_edges"`
	VerticesAlreadyExist map[string]any `json:"vertices_already_exist"`
	MissVertices         map[string]any `json:"miss_vertices"`
}

UpsertResponseResult is the result shape from TigerGraph.

type Version 

type Version struct {
	Edition string `json:"edition"`
	API     string `json:"api"`
	Schema  int    `json:"schema"`
}

type Vertex 

type Vertex struct {
	ID string `json:"id"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.