diff --git a/dgraph/sdks/go.mdx b/dgraph/sdks/go.mdx index 378ce63..b7ed4b0 100644 --- a/dgraph/sdks/go.mdx +++ b/dgraph/sdks/go.mdx @@ -7,7 +7,7 @@ import DgraphWIP from "/snippets/dgraph-wip.mdx" -[![GoDoc](https://godoc.org/github.com/dgraph-io/dgo?status.svg)](https://godoc.org/github.com/dgraph-io/dgo) +[![GoDoc](https://pkg.go.dev/badge/github.com/dgraph-io/dgo/v240)](https://pkg.go.dev/github.com/dgraph-io/dgo/v240) The Go client communicates with the server on the gRPC port (default value 9080). @@ -23,8 +23,15 @@ go get -u -v github.com/dgraph-io/dgo/v210 The full [GoDoc](https://godoc.org/github.com/dgraph-io/dgo) contains documentation for the client API along with examples showing how to use it. -More details on the supported versions can be found at -[this link](https://github.com/hypermodeinc/dgo#supported-versions). +## Supported versions + +Depending on the version of Dgraph that you are connecting to, you should use a +compatible version of this client and their corresponding import paths. + +| Dgraph version | dgo version | dgo import path | +| -------------- | ----------- | ------------------------------- | +| dgraph 23.X.Y | dgo 230.X.Y | `github.com/dgraph-io/dgo/v230` | +| dgraph 24.X.Y | dgo 240.X.Y | `github.com/dgraph-io/dgo/v240` | ## Create the client @@ -66,7 +73,6 @@ func newClient() *dgo.Dgraph { api.NewDgraphClient(d), ) } - ``` ### Multi-tenancy diff --git a/docs.json b/docs.json index d16e968..413df51 100644 --- a/docs.json +++ b/docs.json @@ -59,7 +59,8 @@ "graphs/connect", "graphs/manage-schema", "graphs/manage-data", - "graphs/manage-graph" + "graphs/manage-graph", + "graphs/v25-preview" ] }, { diff --git a/graphs/v25-preview.mdx b/graphs/v25-preview.mdx new file mode 100644 index 0000000..9226f78 --- /dev/null +++ b/graphs/v25-preview.mdx @@ -0,0 +1,303 @@ +--- +title: v25 Preview +description: +--- + +import DgraphWIP from "/snippets/dgraph-wip.mdx" + + + +[![GoDoc](https://pkg.go.dev/badge/github.com/dgraph-io/dgo/v250)](https://pkg.go.dev/github.com/dgraph-io/dgo/v250) + +These APIs are released as part of the preview of Dgraph v25. They are +_experimental_ APIs and subject to change before general availability. Please +share feedback via [Discord](https://discord.hypermode.com) or +[GitHub](https://github.com/hypermodeinc/dgo). + +## Opening a connection + +The dgo package supports connecting to a Dgraph cluster using connection +strings. Dgraph connection strings take the form +`dgraph://{username:password@}host:port?args`. + +`username` and `password` are optional. If username is provided, a password must +also be present. If supplied, these credentials are used to log into a Dgraph +cluster through the ACL mechanism. + +Valid connection string arguments: + +| Arg | Value | Description | +| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| bearertoken | \ | an access token | +| sslmode | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. | + +Using the `Open` function with a connection string: + +```go +// open a connection to an ACL-enabled, non-TLS cluster and login as groot +client, err := dgo.Open("dgraph://groot:password@localhost:9080") +// Check error +defer client.Close() +// Use the clients +``` + +## Advanced client creation + +For more control, you can create a client using the `NewClient` function. + +```go +client, err := dgo.NewClient("localhost:9080", + // add Dgraph ACL credentials + dgo.WithACLCreds("groot", "password"), + // add insecure transport credentials + dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())), +) +// Check error +defer client.Close() +// Use the client +``` + +You can connect to multiple alphas using `NewRoundRobinClient`. + +```go +client, err := dgo.NewRoundRobinClient([]string{"localhost:9181", "localhost:9182", "localhost:9183"}, + // add Dgraph ACL credentials + dgo.WithACLCreds("groot", "password"), + // add insecure transport credentials + dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())), +) +// Check error +defer client.Close() +// Use the client +``` + +## Connecting to Hypermode graph + +You can use either `Open` or `NewClient` to connect to a Hypermode Graph. + +Using `Open` with a connection string: + +```go +client, err := dgo.Open("foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=some-bearer-token") +// Check error +defer client.Close() +``` + +Using `NewClient`: + +```go +client, err := dgo.NewClient("foo-bar.grpc.hypermode.com:443", + dgo.WithBearerToken("some-bearer-token"), + dgo.WithSystemCertPool(), +) +// Check error +defer client.Close() +``` + +## Dropping all data + +In order to drop all data in the Dgraph cluster and start fresh, use the +`DropAllNamespaces` function. + +```go +err := client.DropAllNamespaces(context.TODO()) +// Handle error +``` + +## Set schema + +To set the schema, use the `SetSchema` function. + +```go +sch := ` + name: string @index(exact) . + email: string @index(exact) @unique . + age: int . +` +err := client.SetSchema(context.TODO(), dgo.RootNamespace, sch) +// Handle error +``` + +## Running a mutation + +To run a mutation, use the `RunDQL` function. + +```go +mutationDQL := `{ + set { + _:alice "Alice" . + _:alice "alice@example.com" . + _:alice "29" . + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, mutationDQL) +// Handle error +// Print map of blank UIDs +fmt.Printf("%+v\n", resp.BlankUids) +``` + +## Running a query + +To run a query, use the same `RunDQL` function. + +```go +queryDQL := `{ + alice(func: eq(name, "Alice")) { + name + email + age + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Running a query with variables + +To run a query with variables, using `RunDQLWithVars`. + +```go +queryDQL = `query Alice($name: string) { + alice(func: eq(name, $name)) { + name + email + age + } +}` +vars := map[string]string{"$name": "Alice"} +resp, err := client.RunDQLWithVars(context.TODO(), dgo.RootNamespace, queryDQL, vars) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Running a best effort query + +To run a `BestEffort` query, use the same `RunDQL` function with `TxnOption`. + +```go +queryDQL := `{ + alice(func: eq(name, "Alice")) { + name + email + age + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithBestEffort()) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Running a read-only query + +To run a `ReadOnly` query, use the same `RunDQL` function with `TxnOption`. + +```go +queryDQL := `{ + alice(func: eq(name, "Alice")) { + name + email + age + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithReadOnly()) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Running a query with rdf response + +To get the query response in RDF format instead of JSON format, use the +following `TxnOption`. + +```go +queryDQL := `{ + alice(func: eq(name, "Alice")) { + name + email + age + } +}` +resp, err = client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithResponseFormat(api_v25.RespFormat_RDF)) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Running an Upsert + +The `RunDQL` function also allows you to run upserts as well. + +```go +upsertQuery := `upsert { + query { + user as var(func: eq(email, "alice@example.com")) + } + mutation { + set { + uid(user) "30" . + uid(user) "Alice Sayum" . + } + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, upsertQuery) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +fmt.Printf("%+v\n", resp.BlankUids) +``` + +## Running a conditional upsert + +```go +upsertQuery := `upsert { + query { + user as var(func: eq(email, "alice@example.com")) + } + mutation @if(eq(len(user), 1)) { + set { + uid(user) "30" . + uid(user) "Alice Sayum" . + } + } +}` +resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, upsertQuery) +// Handle error +fmt.Printf("%s\n", resp.QueryResult) +``` + +## Creating a new namespace + +Dgraph v25 supports namespaces that have names. You can create one using the dgo +client. + +```go +err := client.CreateNamespace(context.TODO(), "finance-graph") +// Handle error +``` + +You can now pass this name to `SetSchema`, `RunDQL` or similar functions. + +## Dropping a Namespace + +To drop a namespace: + +```go +err := client.DropNamespace(context.TODO(), "finance-graph") +// Handle error +``` + +## Rename a Namespace + +A namespace can be renamed as follows. + +```go +err := client.RenameNamespace(context.TODO(), "finance-graph", "new-finance-graph") +// Handle error +``` + +## List all namespaces + +```go +namespaces, err := client.ListNamespaces(context.TODO()) +// Handle error +fmt.Printf("%+v\n", namespaces) +```