Essentials
Please read through this to have a better understanding of the nuances that take place when executing commands which we will cover in the upcoming pages.
Namespaces
Namespaces are the way to group and isolate graphs in different environments, such as production and staging. For example you can have a federated graph called my-api in a production and staging namespace. All graph operations and compositions are scoped to graphs present in a particular namespace. Every organization is provided a default namespace which cannot be deleted. You can create additional namespaces with the namespace CLI. Most of the CLI commands respect a -n flag or use default respectively. If you delete a namespace all resources within the namespace are deleted.
Namespaces have the following restrictions:
Must begin and end with alphanumeric characters
Could contain dashes (-) or underscores (_) in between.
Special characters other than the above mentioned are not allowed
Namespaces allow to create and organize multiple environments. Every federated graph represents physically a router instance and every subgraph is a service connected to the router.
Monographs vs Federated Graphs
Federated Graphs
Federated Graphs are the goto method of creating graphs in Cosmo. They compose multiple subgraphs into a unified Federated GraphQL schema.
Monographs
Monographs are graphs that do not perform GraphQL Federation. They consist strictly of a single subgraph that is created internally for you. Monograph commands abstract away the complexities with interacting with that subgraph. Everything supported by Federated Graphs is also supported by Monographs.
Order of execution
The order in which you create graphs does not matter. You can either create subgraphs first or federated graphs. Depending on the labels the appropriate subgraphs will be taken into account for composing your federated graphs.
Labels
Labels are a key=value pair separated by a = sign. Ex: team=A region=us-east-1
You can assign labels to only subgraphs. Labels have the following restrictions
Both key and value must be 63 characters or less (cannot be empty).
Must begin and end with an alphanumeric character ([a-z0-9A-Z]).
Could contain dashes (-), underscores (_), dots (.), and alphanumerics between.
Label Matcher
Label matchers are used with Federated Graphs to determine which subgraphs are chosen for composition. They are a set of labels separated by spaces (or the option) and grouped by commas.
To understand how they work here is an example.
NOTE: You can create subgraphs and federated graphs without labels and label matchers. In such a case, federated graphs with empty label matchers will only compose subgraphs with empty labels. The vice versa is also true, subgraphs without labels can only be composed by federated graphs with empty label matchers.
Federated Graph example
We create a federated graph from all subgraphs that match the label Team A or Team B and Region us-east-1. This can be expressed in the following way:
--label-matcher team=A,team=B region=us-east-1
the long version is
--label-matcher team=A,team=B --label-matcher region=us-east-1
The above matcher translates to logically to (team=A || team=B) && region=us-east-1
Subgraphs example:
Assuming we have the following subgraphs with exact one label:
1. Products --labels team=A
2. Hobbies --labels team=D
3. Users --labels region=us-east-1
Based on the two examples above this setup will create a federated graph consisting of subgraphs Products and Users.
Validate composition
While labeling is a powerful concept it can be very error-prone to understand the final result of your composition. For those reasons, we provide the CLI commands
That allows you to validate if the composition will produce any errors and what the result will look like at the end.
Routing Url
The routing Url must be specified when creating a federated graph or subgraph. In the case of a federated graph, it points to the Url of your Cosmo router. For subgraphs, it is the service URL that the subgraph will be accessible at.
Last updated