|
| 1 | +# Catalog queries using GraphQL |
| 2 | + |
| 3 | +!!! warning "Alpha Feature" |
| 4 | + The GraphQL endpoint is an **alpha feature** controlled by the `GraphQLCatalogQueries` feature gate. |
| 5 | + The API and behavior may change in future releases. |
| 6 | + |
| 7 | +After you [add a catalog of extensions](../../tutorials/add-catalog.md) to your cluster, you can query the catalog using GraphQL for flexible, structured queries with precise field selection. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +* You have added a ClusterCatalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster. |
| 12 | +* The `GraphQLCatalogQueries` feature gate is enabled in catalogd. |
| 13 | + |
| 14 | +!!! note |
| 15 | + By default, Catalogd is installed with TLS enabled for the catalog webserver. |
| 16 | + The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag. |
| 17 | + |
| 18 | +You also need to port forward the catalog server service: |
| 19 | + |
| 20 | +``` terminal |
| 21 | +kubectl -n olmv1-system port-forward svc/catalogd-service 8443:443 |
| 22 | +``` |
| 23 | + |
| 24 | +## GraphQL Endpoint |
| 25 | + |
| 26 | +The GraphQL endpoint is available at: |
| 27 | + |
| 28 | +``` |
| 29 | +https://localhost:8443/catalogs/<catalog-name>/api/v1/graphql |
| 30 | +``` |
| 31 | + |
| 32 | +All queries must be sent as **HTTP POST** requests with a JSON body containing a `query` field. |
| 33 | + |
| 34 | +## Understanding GraphQL Field Names |
| 35 | + |
| 36 | +**IMPORTANT**: GraphQL field names are automatically generated from catalog schema names. |
| 37 | + |
| 38 | +### Naming Convention |
| 39 | + |
| 40 | +Schema names are converted to GraphQL field names using this process: |
| 41 | + |
| 42 | +1. Remove dots and special characters: `olm.bundle` → `olmbundle` |
| 43 | +2. Convert to lowercase: `OLM.Bundle` → `olmbundle` |
| 44 | +3. Append 's' for pluralization: `olmbundle` → `olmbundles` |
| 45 | + |
| 46 | +**Examples:** |
| 47 | + |
| 48 | +| Schema Name | GraphQL Field Name | |
| 49 | +|-------------|-------------------| |
| 50 | +| `olm.bundle` | `olmbundles` | |
| 51 | +| `olm.package` | `olmpackages` | |
| 52 | +| `olm.channel` | `olmchannels` | |
| 53 | +| `helm.chart` | `helmcharts` | |
| 54 | + |
| 55 | +### Discovering Available Fields |
| 56 | + |
| 57 | +To find the exact field names available for your catalog, use GraphQL introspection: |
| 58 | + |
| 59 | +``` terminal |
| 60 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 61 | + -H "Content-Type: application/json" \ |
| 62 | + -d '{ |
| 63 | + "query": "{ __schema { queryType { fields { name description } } } }" |
| 64 | + }' | jq |
| 65 | +``` |
| 66 | + |
| 67 | +This returns all available query fields for the catalog, including the automatically generated schema-based fields. |
| 68 | + |
| 69 | +!!! warning "Pluralization Limitations" |
| 70 | + The current implementation appends 's' to schema names for pluralization. This may not produce grammatically correct English plurals in all cases (e.g., `index` → `indexs` instead of `indices`). When creating custom schemas, use singular nouns that pluralize well with a simple 's' suffix. |
| 71 | + |
| 72 | +## Basic Queries |
| 73 | + |
| 74 | +### Catalog Summary |
| 75 | + |
| 76 | +Get an overview of schemas and object counts in the catalog: |
| 77 | + |
| 78 | +``` terminal |
| 79 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 80 | + -H "Content-Type: application/json" \ |
| 81 | + -d '{ |
| 82 | + "query": "{ summary { totalSchemas schemas { name totalObjects totalFields } } }" |
| 83 | + }' | jq |
| 84 | +``` |
| 85 | + |
| 86 | +### Query Bundles |
| 87 | + |
| 88 | +List bundles with specific fields: |
| 89 | + |
| 90 | +``` terminal |
| 91 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 92 | + -H "Content-Type: application/json" \ |
| 93 | + -d '{ |
| 94 | + "query": "{ olmbundles(limit: 5, offset: 0) { name package image } }" |
| 95 | + }' | jq |
| 96 | +``` |
| 97 | + |
| 98 | +### Query Packages |
| 99 | + |
| 100 | +List packages with metadata: |
| 101 | + |
| 102 | +``` terminal |
| 103 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 104 | + -H "Content-Type: application/json" \ |
| 105 | + -d '{ |
| 106 | + "query": "{ olmpackages(limit: 10) { name description defaultChannel } }" |
| 107 | + }' | jq |
| 108 | +``` |
| 109 | + |
| 110 | +### Query Channels |
| 111 | + |
| 112 | +List channels: |
| 113 | + |
| 114 | +``` terminal |
| 115 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 116 | + -H "Content-Type: application/json" \ |
| 117 | + -d '{ |
| 118 | + "query": "{ olmchannels { name package entries } }" |
| 119 | + }' | jq |
| 120 | +``` |
| 121 | + |
| 122 | +## Advanced Queries |
| 123 | + |
| 124 | +### Pagination |
| 125 | + |
| 126 | +All schema-based queries support pagination via `limit` and `offset` arguments: |
| 127 | + |
| 128 | +``` terminal |
| 129 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 130 | + -H "Content-Type: application/json" \ |
| 131 | + -d '{ |
| 132 | + "query": "{ olmbundles(limit: 10, offset: 20) { name } }" |
| 133 | + }' | jq |
| 134 | +``` |
| 135 | + |
| 136 | +### Nested Field Selection |
| 137 | + |
| 138 | +Select only the fields you need, including array-nested objects: |
| 139 | + |
| 140 | +``` terminal |
| 141 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 142 | + -H "Content-Type: application/json" \ |
| 143 | + -d '{ |
| 144 | + "query": "{ olmpackages { name channels { name entries { name } } } }" |
| 145 | + }' | jq |
| 146 | +``` |
| 147 | + |
| 148 | +**Note:** Non-array nested fields (like `icon`) are returned as JSON strings. To access their data, request the field as a scalar and parse the JSON: |
| 149 | + |
| 150 | +``` terminal |
| 151 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 152 | + -H "Content-Type: application/json" \ |
| 153 | + -d '{ |
| 154 | + "query": "{ olmpackages { name icon } }" |
| 155 | + }' | jq '.data.olmpackages[] | .icon | fromjson' |
| 156 | +``` |
| 157 | + |
| 158 | +### Complex Bundle Properties |
| 159 | + |
| 160 | +Query bundle properties with their type and value fields: |
| 161 | + |
| 162 | +``` terminal |
| 163 | +curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \ |
| 164 | + -H "Content-Type: application/json" \ |
| 165 | + -d '{ |
| 166 | + "query": "{ olmbundles(limit: 5) { name properties { type value } } }" |
| 167 | + }' | jq |
| 168 | +``` |
| 169 | + |
| 170 | +**Note:** The `properties` field contains an array of objects, each with a `type` string and a `value` field that can contain complex nested data. GraphQL will return the full JSON structure for the `value` field. |
| 171 | + |
| 172 | +## Comparing GraphQL vs Metas Endpoint |
| 173 | + |
| 174 | +| Feature | GraphQL (`/api/v1/graphql`) | Metas (`/api/v1/metas`) | |
| 175 | +|---------|---------------------------|------------------------| |
| 176 | +| Field selection | Precise - request only needed fields | All fields always returned | |
| 177 | +| Query complexity | Rich queries with nested objects | Simple parameter-based filtering | |
| 178 | +| Response size | Minimal - only requested data | Full objects always returned | |
| 179 | +| Schema discovery | Introspection built-in | External documentation needed | |
| 180 | +| Pagination | Built-in `limit` and `offset` | Manual implementation required | |
| 181 | +| HTTP Method | POST only | GET supported | |
| 182 | +| Feature status | Alpha (feature gate required) | Stable | |
| 183 | + |
| 184 | +**When to use GraphQL:** |
| 185 | +- You need specific fields from large objects |
| 186 | +- You want to query related data in a single request |
| 187 | +- You need structured, typed responses |
| 188 | +- You're building a UI or client that benefits from precise data fetching |
| 189 | + |
| 190 | +**When to use Metas endpoint:** |
| 191 | +- You need simple, stable API |
| 192 | +- You're doing basic filtering by schema/package/name |
| 193 | +- You want to use GET requests for caching |
| 194 | +- You need guaranteed API stability |
| 195 | + |
| 196 | +## Limitations |
| 197 | + |
| 198 | +1. **Pluralization**: Schema names are pluralized by appending 's', which may not be grammatically correct for all words |
| 199 | +2. **Schema naming**: Full schema names (including namespace/prefix) are preserved in field names (`olm.bundle` → `olmbundles`, not `bundles`) |
| 200 | +3. **POST only**: GraphQL endpoint only accepts POST requests, unlike the metas endpoint which supports GET |
| 201 | +4. **Alpha stability**: API may change in future releases while in alpha |
| 202 | + |
| 203 | +## Enabling the GraphQL Feature |
| 204 | + |
| 205 | +The GraphQL endpoint is controlled by the `GraphQLCatalogQueries` feature gate. To enable it: |
| 206 | + |
| 207 | +``` yaml |
| 208 | +args: |
| 209 | + - --feature-gates=GraphQLCatalogQueries=true |
| 210 | +``` |
| 211 | +
|
| 212 | +See [enable webhook support](enable-webhook-support.md) for more details on configuring feature gates. |
0 commit comments