Skip to content

Latest commit

 

History

History
113 lines (82 loc) · 4.61 KB

discovery.md

File metadata and controls

113 lines (82 loc) · 4.61 KB

StackQL Discovery Operations (meta queries)

Contents
  1. Pulling a provider from the registry
  2. Showing all services in a provider
  3. Showing all resources in a service
  4. Describe a resource
  5. Show all available methods in a resource

StackQL is built upon the provider's API specification as OpenAPI extensions which are mastered in the StackQL Provider Registry; docs for each provider are available in the Registry Docs.

Meta queries, or queries that enumerate and describe the services, resources, and operations available in a provider, are available within StackQL using the DESCRIBE and SHOW commands.

StackQL presents a consistent ORM for every provider, which is comprised of services, resources, and methods. The ORM is a direct reflection of the provider's underlying API. The ORM (resource hierarchy) is shown here:

flowchart LR;
    P[Provider]-->S[Service];
    S-->R[Resource];
    R-->M[Method];
Loading
  • Provider: cloud, SaaS or API provider (will have its own specific authentication), for example: aws, google
  • Service: a service endpoint or grouping of related resources, for example: aws.ec2 or google.storage
  • Resource: an entity which has attributes and methods (the thing you want to query, deploy or manage), for example: aws.ec2.instances or google.storage.buckets
  • Method: operations exposed on the resource by the provider, these are mapped to SQL verbs where possible such as SELECT, INSERT, UPDATE, DELETE. For lifecycle methods (non-CRUD operations) methods are accessible using the EXEC command, for example: EXEC google.compute.instances.start

Pulling a provider from the registry

StackQL providers can be installed or updated from the registry API, which can be accessed using the REGISTRY commands. For example, to list all available providers, run the following:

REGISTRY LIST;

This command will show the latest available version for each provider. To see all available versions for a given provider, run the following:

REGISTRY LIST google;

To pull the latest version for a specific provider, run the following:

REGISTRY PULL google;

if you wanted to pull a previous version of a provider, supply the version SemVer, e.g., REGISTRY PULL google v23.01.00104;

The signed provider documents are downloaded to the .stackql directory in the current working directory. To show all providers installed, run the following command:

SHOW PROVIDERS;

Running meta queries

Meta queries can be run without authenticating to the provider. Some examples are provided below:

Showing all services in a provider

To show all services in a provider, run the following:

SHOW SERVICES IN google;

to filter by service name, run the following:

SHOW SERVICES IN google WHERE name = 'compute';

to fuzzy match a service name (and return one or more matches), run the following:

SHOW SERVICES IN google LIKE '%container%';

Showing all resources in a service

To show all resources in a service, run the following:

SHOW RESOURCES IN google.compute;

Filtering and fuzzy matching is also available for resources.

Describe a resource

Once you have identified a resource you want to query, provision or manipulate, you can run the following:

DESCRIBE google.compute.instances;

This will return fields in the resource along with their respective data types. To include field descriptions, run the following:

DESCRIBE EXTENDED google.compute.instances;

Show all available methods in a resource

To show all available methods in a resource, run the following:

SHOW METHODS IN google.compute.instances;

The EXTENDED keyword can also be used to show method descriptions, for example:

SHOW EXTENDED METHODS IN google.compute.instances;