Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update /admin endpoint documentation. #6415

Merged
merged 10 commits into from
Sep 15, 2020
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added p/000000.vlog
Binary file not shown.
1 change: 1 addition & 0 deletions p/KEYREGISTRY
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
�L��a�޻u3ZG��Hello Badger
1 change: 1 addition & 0 deletions p/LOCK
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
23105
Binary file added p/MANIFEST
Binary file not shown.
Binary file added w/000000.vlog
Binary file not shown.
1 change: 1 addition & 0 deletions w/KEYREGISTRY
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
:P�տ*�Xn�جE�xHello Badger
1 change: 1 addition & 0 deletions w/LOCK
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
23105
Binary file added w/MANIFEST
Binary file not shown.
303 changes: 277 additions & 26 deletions wiki/content/graphql/admin/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,40 +45,291 @@ At `/admin` you'll find an admin API for administering your GraphQL instance. T
Here are the important types, queries, and mutations from the admin schema.

```graphql
type GQLSchema {
id: ID!
schema: String!
generatedSchema: String!
}

type UpdateGQLSchemaPayload {
gqlSchema: GQLSchema
}

input UpdateGQLSchemaInput {
set: GQLSchemaPatch!
}

input GQLSchemaPatch {
schema: String!
}

type Query {
getGQLSchema: GQLSchema
health: Health
}

type Mutation {
updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload
}
scalar DateTime

"""
Data about the GraphQL schema being served by Dgraph.
"""
type GQLSchema @dgraph(type: "dgraph.graphql") {
id: ID!

"""
Input schema (GraphQL types) that was used in the latest schema update.
"""
schema: String! @dgraph(pred: "dgraph.graphql.schema")

"""
The GraphQL schema that was generated from the 'schema' field.
This is the schema that is being served by Dgraph at /graphql.
"""
generatedSchema: String!
}

type Cors @dgraph(type: "dgraph.cors"){
acceptedOrigins: [String]
}

"""
SchemaHistory contains the schema and the time when the schema has been created.
"""
type SchemaHistory @dgraph(type: "dgraph.graphql.history") {
schema: String! @id @dgraph(pred: "dgraph.graphql.schema_history")
created_at: DateTime! @dgraph(pred: "dgraph.graphql.schema_created_at")
}

"""
A NodeState is the state of an individual node in the Dgraph cluster.
"""
type NodeState {

"""
Node type : either 'alpha' or 'zero'.
"""
instance: String

"""
Address of the node.
"""
address: String

"""
Node health status : either 'healthy' or 'unhealthy'.
"""
status: String

"""
The group this node belongs to in the Dgraph cluster.
See : https://dgraph.io/docs/deploy/#cluster-setup.
"""
group: String

"""
Version of the Dgraph binary.
"""
version: String

"""
Time in nanoseconds since the node started.
"""
uptime: Int

"""
Time in Unix epoch time that the node was last contacted by another Zero or Alpha node.
"""
lastEcho: Int

"""
List of ongoing operations in the background.
"""
ongoing: [String]

"""
List of predicates for which indexes are built in the background.
"""
indexing: [String]

"""
List of Enterprise Features that are enabled.
"""
ee_features: [String]
}

type MembershipState {
counter: Int
groups: [ClusterGroup]
zeros: [Member]
maxLeaseId: Int
maxTxnTs: Int
maxRaftId: Int
removed: [Member]
cid: String
license: License
}

type ClusterGroup {
id: Int
members: [Member]
tablets: [Tablet]
snapshotTs: Int
checksum: Int
}

type Member {
id: Int
groupId: Int
addr: String
leader: Boolean
amDead: Boolean
lastUpdate: Int
clusterInfoOnly: Boolean
forceGroupId: Boolean
}

type Tablet {
groupId: Int
predicate: String
force: Boolean
space: Int
remove: Boolean
readOnly: Boolean
moveTs: Int
}

type License {
user: String
maxNodes: Int
expiryTs: Int
enabled: Boolean
}

directive @dgraph(type: String, pred: String) on OBJECT | INTERFACE | FIELD_DEFINITION
directive @id on FIELD_DEFINITION
directive @secret(field: String!, pred: String) on OBJECT | INTERFACE


type UpdateGQLSchemaPayload {
gqlSchema: GQLSchema
}

input UpdateGQLSchemaInput {
set: GQLSchemaPatch!
}

input GQLSchemaPatch {
schema: String!
}

input ExportInput {
format: String

"""
Destination for the backup: e.g. Minio or S3 bucket or /absolute/path
"""
destination: String

"""
Access key credential for the destination.
"""
accessKey: String

"""
Secret key credential for the destination.
"""
secretKey: String

"""
AWS session token, if required.
"""
sessionToken: String

"""
Set to true to allow backing up to S3 or Minio bucket that requires no credentials.
"""
anonymous: Boolean
}

type Response {
code: String
message: String
}

type ExportPayload {
response: Response
exportedFiles: [String]
}

type DrainingPayload {
response: Response
}

type ShutdownPayload {
response: Response
}

input ConfigInput {

"""
Estimated memory the LRU cache can take. Actual usage by the process would be
more than specified here. (default -1 means no set limit)
"""
lruMb: Float

"""
True value of logRequest enables logging of all the requests coming to alphas.
False value of logRequest disables above.
"""
logRequest: Boolean
}

type ConfigPayload {
response: Response
}

type Config {
lruMb: Float
}

type Query {
getGQLSchema: GQLSchema
health: [NodeState]
state: MembershipState
config: Config
getAllowedCORSOrigins: Cors
querySchemaHistory(first: Int, offset: Int): [SchemaHistory]
}

type Mutation {

"""
Update the Dgraph cluster to serve the input schema. This may change the GraphQL
schema, the types and predicates in the Dgraph schema, and cause indexes to be recomputed.
"""
updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload

"""
Starts an export of all data in the cluster. Export format should be 'rdf' (the default
if no format is given), or 'json'.
See : https://dgraph.io/docs/deploy/#export-database
"""
export(input: ExportInput!): ExportPayload

"""
Set (or unset) the cluster draining mode. In draining mode no further requests are served.
"""
draining(enable: Boolean): DrainingPayload

"""
Shutdown this node.
"""
shutdown: ShutdownPayload

"""
Alter the node's config.
"""
config(input: ConfigInput!): ConfigPayload

replaceAllowedCORSOrigins(origins: [String]): Cors

}
```

You'll notice that the /admin schema is very much the same as the schemas generated by Dgraph GraphQL.

* The `health` query lets you know if everything is connected and if there's a schema currently being served at `/graphql`.
* The `state` query returns the current state of the cluster and group membership information. For more information about `state` see [here](https://dgraph.io/docs/deploy/dgraph-zero/#more-about-state-endpoint).
* The `config` query returns the configuration options of the cluster set at the time of starting it.
* The `getGQLSchema` query gets the current GraphQL schema served at `/graphql`, or returns null if there's no such schema.
* The `getAllowedCORSOrigins` query returns your CORS policy.
* The `updateGQLSchema` mutation allows you to change the schema currently served at `/graphql`.

## Enterprise Features

Enterprise Features like ACL, Backups and Restore are also available using the GraphQL API at `/admin` endpoint.

* [ACL](https://dgraph.io/docs/enterprise-features/access-control-lists/#using-graphql-admin-api).
* [Backups](https://dgraph.io/docs/enterprise-features/binary-backups/#create-a-backup).
* [Restore](https://dgraph.io/docs/enterprise-features/binary-backups/#restore-from-backup).

## First Start

On first starting with a blank database:
Expand Down