refactor: Change terminology from query to request (#1054)

- Resolves #455

- DESCRIPTION:

This PR changes existing terminology to comply with the following terminology definitions:

DefraDB Terminology:
* (1) `Request` is the top-level term that encapsulates all the operations (`query` and `mutation` ops).
* (2) `Query Request` or `Request Query` are same as (1) but only for situations where we need to use the word "Query" for some reason (say for external use for example in `cli` package), so the `Request` descriptor clarifies the type of "Query" this is.
* (3) `Query Operation` implies that the request is a "read-only request", but note that if we loosely say `Query Request` that does not mean a read-only operation according to (2).
* (4) `Query` loosely the same as (3), BUT STRONGLY AVOID USING ON IT'S OWN.
* (5) `Mutation Operation` implies that the request is a "write request".
* (6) `Mutation Request` implies that the request's operation is of type `mutation`. Note: `(6)` and `(5)` can be used interchangeably but `(2)` and `(3)` can not.
* (7) `Mutation` is loosely the same as (5) and (6) but avoid using this term.
 
With the above definition, we can use other descriptors to specify the type of request it is, for example: "Explain request" or "Subscription Request". But the only gotcha / confusing rule we need to worry about is that `Query Request` is not the same as `Query Operation`. The use of the word `Query` with another descriptor assumes (4), for example: `Query Plan` is a plan that is made from a read-only query.  

Throughout the codebase (excluding 3rd party stuff, eg. ipfs), we should avoid the use of (2), (4), and (7) to avoid confusion. The only exception to (4) I can see is when we say "Defra Query Language" (because this is not referring to the query operation).

api/http/errors.go

@@ -32,7 +32,7 @@ var (
 	ErrDatabaseNotAvailable = errors.New("no database available")
 	ErrFormNotSupported     = errors.New("content type application/x-www-form-urlencoded not yet supported")
 	ErrBodyEmpty            = errors.New("body cannot be empty")
-	ErrMissingGQLQuery      = errors.New("missing GraphQL query")
+	ErrMissingGQLRequest    = errors.New("missing GraphQL request")
 	ErrPeerIdUnavailable    = errors.New("no peer ID available. P2P might be disabled")
 	ErrStreamingUnsupported = errors.New("streaming unsupported")
 	ErrNoEmail              = errors.New("email address must be specified for tls with autocert")

api/http/handlerfuncs.go

@@ -78,12 +78,12 @@ func dumpHandler(rw http.ResponseWriter, req *http.Request) {
 }
 
 type gqlRequest struct {
-	Query string `json:"query"`
+	Request string `json:"query"`
 }
 
 func execGQLHandler(rw http.ResponseWriter, req *http.Request) {
-	query := req.URL.Query().Get("query")
-	if query == "" {
+	request := req.URL.Query().Get("query")
+	if request == "" {
 		// extract the media type from the content-type header
 		contentType, _, err := mime.ParseMediaType(req.Header.Get("Content-Type"))
 		// mime.ParseMediaType will return an error (mime: no media type)
@@ -105,7 +105,7 @@ func execGQLHandler(rw http.ResponseWriter, req *http.Request) {
 				return
 			}
 
-			query = gqlReq.Query
+			request = gqlReq.Request
 
 		case contentTypeFormURLEncoded:
 			handleErr(
@@ -129,13 +129,13 @@ func execGQLHandler(rw http.ResponseWriter, req *http.Request) {
 				handleErr(req.Context(), rw, errors.WithStack(err), http.StatusBadRequest)
 				return
 			}
-			query = string(body)
+			request = string(body)
 		}
 	}
 
-	// if at this point query is still empty, return an error
-	if query == "" {
-		handleErr(req.Context(), rw, ErrMissingGQLQuery, http.StatusBadRequest)
+	// if at this point request is still empty, return an error
+	if request == "" {
+		handleErr(req.Context(), rw, ErrMissingGQLRequest, http.StatusBadRequest)
 		return
 	}
 
@@ -144,7 +144,7 @@ func execGQLHandler(rw http.ResponseWriter, req *http.Request) {
 		handleErr(req.Context(), rw, err, http.StatusInternalServerError)
 		return
 	}
-	result := db.ExecQuery(req.Context(), query)
+	result := db.ExecRequest(req.Context(), request)
 
 	if result.Pub != nil {
 		subscriptionHandler(result.Pub, rw, req)

api/http/handlerfuncs_test.go

@@ -172,10 +172,10 @@ func TestExecGQLWithEmptyBody(t *testing.T) {
 		ResponseData:   &errResponse,
 	})
 
-	assert.Contains(t, errResponse.Errors[0].Extensions.Stack, "missing GraphQL query")
+	assert.Contains(t, errResponse.Errors[0].Extensions.Stack, "missing GraphQL request")
 	assert.Equal(t, http.StatusBadRequest, errResponse.Errors[0].Extensions.Status)
 	assert.Equal(t, "Bad Request", errResponse.Errors[0].Extensions.HTTPError)
-	assert.Equal(t, "missing GraphQL query", errResponse.Errors[0].Message)
+	assert.Equal(t, "missing GraphQL request", errResponse.Errors[0].Message)
 }
 
 type mockReadCloser struct {

cli/query.go → cli/request.go

@@ -23,23 +23,23 @@ import (
 	"github.com/sourcenetwork/defradb/errors"
 )
 
-var queryCmd = &cobra.Command{
-	Use:   "query [query]",
-	Short: "Send a DefraDB GraphQL query",
-	Long: `Send a DefraDB GraphQL query to the database.
+var requestCmd = &cobra.Command{
+	Use:   "query [query request]",
+	Short: "Send a DefraDB GraphQL query request",
+	Long: `Send a DefraDB GraphQL query request to the database.
 
-A query can be sent as a single argument. Example command:
+A query request can be sent as a single argument. Example command:
 defradb client query 'query { ... }'
 
 Or it can be sent via stdin by using the '-' special syntax. Example command:
-cat query.graphql | defradb client query -
+cat request.graphql | defradb client query -
 
 A GraphQL client such as GraphiQL (https://github.com/graphql/graphiql) can be used to interact
 with the database more conveniently.
 
 To learn more about the DefraDB GraphQL Query Language, refer to https://docs.source.network.`,
 	RunE: func(cmd *cobra.Command, args []string) (err error) {
-		var query string
+		var request string
 
 		fi, err := os.Stdin.Stat()
 		if err != nil {
@@ -71,16 +71,16 @@ To learn more about the DefraDB GraphQL Query Language, refer to https://docs.so
 				return errors.Wrap("failed to read stdin", err)
 			}
 			if len(stdin) == 0 {
-				return errors.New("no query in stdin provided")
+				return errors.New("no query request in stdin provided")
 			} else {
-				query = stdin
+				request = stdin
 			}
 		} else {
-			query = args[0]
+			request = args[0]
 		}
 
-		if query == "" {
-			return errors.New("query cannot be empty")
+		if request == "" {
+			return errors.New("request cannot be empty")
 		}
 
 		endpoint, err := httpapi.JoinPaths(cfg.API.AddressToURL(), httpapi.GraphQLPath)
@@ -89,12 +89,12 @@ To learn more about the DefraDB GraphQL Query Language, refer to https://docs.so
 		}
 
 		p := url.Values{}
-		p.Add("query", query)
+		p.Add("query", request)
 		endpoint.RawQuery = p.Encode()
 
 		res, err := http.Get(endpoint.String())
 		if err != nil {
-			return errors.Wrap("failed query", err)
+			return errors.Wrap("failed request", err)
 		}
 
 		defer func() {
@@ -135,5 +135,5 @@ To learn more about the DefraDB GraphQL Query Language, refer to https://docs.so
 }
 
 func init() {
-	clientCmd.AddCommand(queryCmd)
+	clientCmd.AddCommand(requestCmd)
 }

cli/root.go

@@ -28,7 +28,7 @@ var rootCmd = &cobra.Command{
 	Short: "DefraDB Edge Database",
 	Long: `DefraDB is the edge database to power the user-centric future.
 
-Start a database node, query a local or remote node, and much more.
+Start a database node, issue a request to a local or remote node, and much more.
 
 DefraDB is released under the BSL license, (c) 2022 Democratized Data Foundation.
 See https://docs.source.network/BSL.txt for more information.

cli/start.go

@@ -344,7 +344,7 @@ func start(ctx context.Context) (*defraInstance, error) {
 		log.FeedbackInfo(
 			ctx,
 			fmt.Sprintf(
-				"Providing HTTP API at %s%s. Use the GraphQL query endpoint at %s%s/graphql ",
+				"Providing HTTP API at %s%s. Use the GraphQL request endpoint at %s%s/graphql ",
 				cfg.API.AddressToURL(),
 				httpapi.RootPath,
 				cfg.API.AddressToURL(),

client/db.go

@@ -31,8 +31,8 @@ type DB interface {
 	Blockstore() blockstore.Blockstore
 
 	NewTxn(context.Context, bool) (datastore.Txn, error)
-	ExecQuery(context.Context, string) *QueryResult
-	ExecTransactionalQuery(ctx context.Context, query string, txn datastore.Txn) *QueryResult
+	ExecRequest(context.Context, string) *RequestResult
+	ExecTransactionalRequest(context.Context, string, datastore.Txn) *RequestResult
 	Close(context.Context)
 
 	Events() events.Events
@@ -57,7 +57,7 @@ type GQLResult struct {
 	Data   any   `json:"data"`
 }
 
-type QueryResult struct {
+type RequestResult struct {
 	GQL GQLResult
 	Pub *events.Publisher[events.Update]
 }

client/descriptions.go

@@ -84,9 +84,10 @@ type IndexDescription struct {
 	// A Book type can have many Categories,
 	// and Categories can belong to many Books.
 	//
-	// If we query more for Books, then Categories directly, then
+	// If we request Books more, then Categories directly, then
 	// we can set the Book type as the Primary type.
 	Junction bool
+
 	// RelationType is only used in the Index is a Junction Index.
 	// It specifies what the other type is in the Many-to-Many
 	// relationship.

client/document.go

@@ -26,7 +26,7 @@ import (
 // Documents in this case refer to the core database type of DefraDB which is a
 // "NoSQL Document Datastore".
 //
-// This section is not concerned with the outer query layer used to interact with the
+// This section is not concerned with the outer request layer used to interact with the
 // Document API, but instead is solely concerned with carrying out the internal API
 // operations.
 //

client/request/consts.go

@@ -39,8 +39,8 @@ const (
 
 	ExplainLabel = "explain"
 
-	LatestCommitsQueryName = "latestCommits"
-	CommitsQueryName       = "commits"
+	LatestCommitsName = "latestCommits"
+	CommitsName       = "commits"
 
 	CommitTypeName  = "Commit"
 	LinksFieldName  = "links"
@@ -78,8 +78,8 @@ var (
 	}
 
 	CommitQueries = map[string]struct{}{
-		LatestCommitsQueryName: {},
-		CommitsQueryName:       {},
+		LatestCommitsName: {},
+		CommitsName:       {},
 	}
 
 	VersionFields = []string{

client/request/doc.go

@@ -9,6 +9,6 @@
 // licenses/APL.txt.
 
 /*
-Package request defines the GraphQL types used by the query service.
+Package request defines the GraphQL types used by the request issuing service.
 */
 package request

client/request/mutation.go

@@ -21,13 +21,9 @@ const (
 	DeleteObjects
 )
 
-// Mutation is a field on the MutationType
-// of a graphql query. It includes all the possible
-// arguments and all
-//
-// @todo: Change name to ObjectMutation to indicate
-// generated object mutation actions
-type Mutation struct {
+// ObjectMutation is a field on the `mutation` operation of a graphql request. It includes
+// all the possible arguments.
+type ObjectMutation struct {
 	Field
 	Type MutationType
 
@@ -44,7 +40,7 @@ type Mutation struct {
 
 // ToSelect returns a basic Select object, with the same Name, Alias, and Fields as
 // the Mutation object. Used to create a Select planNode for the mutation return objects.
-func (m Mutation) ToSelect() *Select {
+func (m ObjectMutation) ToSelect() *Select {
 	return &Select{
 		Field: Field{
 			Name:  m.Collection,

client/request/select.go

@@ -25,15 +25,15 @@ const (
 )
 
 // Select is a complex Field with strong typing.
-// It is used for sub-types in a query.
-// Includes fields, and query arguments like filters, limits, etc.
+// It is used for sub-types in a request.
+// Includes fields, and request arguments like filters, limits, etc.
 type Select struct {
 	Field
 
 	DocKeys immutable.Option[[]string]
 	CID     immutable.Option[string]
 
-	// Root is the top level query parsed type
+	// Root is the top level type of parsed request
 	Root SelectionType
 
 	Limit   immutable.Option[uint64]

client/request/subscription.go

@@ -15,7 +15,7 @@ import (
 )
 
 // ObjectSubscription is a field on the SubscriptionType
-// of a graphql query. It includes all the possible
+// of a graphql request. It includes all the possible
 // arguments
 type ObjectSubscription struct {
 	Field

connor/time/equality.go

@@ -13,7 +13,7 @@ func Equal(condition, data any) bool {
 			// parsing incoming data here, or
 			// if the DB should handle this.
 			// (Note: This isnt the user provided
-			// condition on a query, but the data
+			// condition on a request, but the data
 			// stored in DB for a document
 			dt, err := time.Parse(time.RFC3339, d)
 			if err != nil {

core/parser.go

@@ -31,13 +31,13 @@ type SchemaDefinition struct {
 }
 
 // Parser represents the object responsible for handling stuff specific to a query language.
-// This includes schema and query parsing, and introspection.
+// This includes schema and request parsing, and introspection.
 type Parser interface {
 	// Returns true if the given string is an introspection request.
 	IsIntrospection(request string) bool
 
 	// Executes the given introspection request.
-	ExecuteIntrospection(request string) *client.QueryResult
+	ExecuteIntrospection(request string) *client.RequestResult
 
 	// Parses the given request, returning a strongly typed model of that request.
 	Parse(request string) (*request.Request, []error)

db/collection.go

@@ -549,7 +549,7 @@ func (c *collection) Update(ctx context.Context, doc *client.Document) error {
 }
 
 // Contract: DB Exists check is already performed, and a doc with the given key exists.
-// Note: Should we CompareAndSet the update, IE: Query the state, and update if changed
+// Note: Should we CompareAndSet the update, IE: Query(read-only) the state, and update if changed
 // or, just update everything regardless.
 // Should probably be smart about the update due to the MerkleCRDT overhead, shouldn't
 // add to the bloat.

db/collection_delete.go

@@ -183,29 +183,29 @@ func (c *collection) deleteWithFilter(
 	txn datastore.Txn,
 	filter any,
 ) (*client.DeleteResult, error) {
-	// Do a selection query to scan through documents using the given filter.
-	query, err := c.makeSelectionQuery(ctx, txn, filter)
+	// Make a selection plan that will scan through only the documents with matching filter.
+	selectionPlan, err := c.makeSelectionPlan(ctx, txn, filter)
 	if err != nil {
 		return nil, err
 	}
-	if err := query.Start(); err != nil {
+	if err := selectionPlan.Start(); err != nil {
 		return nil, err
 	}
 
-	// If the query object isn't properly closed at any exit point log the error.
+	// If the plan isn't properly closed at any exit point log the error.
 	defer func() {
-		if err := query.Close(); err != nil {
-			log.ErrorE(ctx, "Failed to close query after filter delete", err)
+		if err := selectionPlan.Close(); err != nil {
+			log.ErrorE(ctx, "Failed to close the request plan, after filter delete", err)
 		}
 	}()
 
 	results := &client.DeleteResult{
 		DocKeys: make([]string, 0),
 	}
 
-	// Keep looping until results from the filter query have been iterated through.
+	// Keep looping until results from the selection plan have been iterated through.
 	for {
-		next, err := query.Next()
+		next, err := selectionPlan.Next()
 		if err != nil {
 			return nil, err
 		}
@@ -215,7 +215,7 @@ func (c *collection) deleteWithFilter(
 			break
 		}
 
-		doc := query.Value()
+		doc := selectionPlan.Value()
 		// Extract the dockey in the string format from the document value.
 		docKey := doc.GetKey()