openshift · openshift-bot · May 26, 2026 · May 26, 2026 · May 26, 2026 · May 26, 2026
diff --git a/cmd/catalogd/main.go b/cmd/catalogd/main.go
@@ -365,12 +365,27 @@ func run(ctx context.Context) error {
 		return err
 	}
 
-	localStorage = &storage.LocalDirV1{
-		RootDir:            storeDir,
-		RootURL:            baseStorageURL,
-		EnableMetasHandler: features.CatalogdFeatureGate.Enabled(features.APIV1MetasHandler),
+	var metasMode storage.MetasHandlerMode
+	if features.CatalogdFeatureGate.Enabled(features.APIV1MetasHandler) {
+		metasMode = storage.MetasHandlerEnabled
+	} else {
+		metasMode = storage.MetasHandlerDisabled
 	}
 
+	var graphqlMode storage.GraphQLQueriesMode
+	if features.CatalogdFeatureGate.Enabled(features.GraphQLCatalogQueries) {
+		graphqlMode = storage.GraphQLQueriesEnabled
+	} else {
+		graphqlMode = storage.GraphQLQueriesDisabled
+	}
+
+	localStorage = storage.NewLocalDirV1(
+		storeDir,
+		baseStorageURL,
+		metasMode,
+		graphqlMode,
+	)
+
 	// Config for the catalogd web server
 	catalogServerConfig := serverutil.CatalogServerConfig{
 		ExternalAddr: cfg.externalAddr,

diff --git a/docs/draft/howto/catalog-queries-graphql-endpoint.md b/docs/draft/howto/catalog-queries-graphql-endpoint.md
@@ -0,0 +1,212 @@
+# Catalog queries using GraphQL
+
+!!! warning "Alpha Feature"
+    The GraphQL endpoint is an **alpha feature** controlled by the `GraphQLCatalogQueries` feature gate.
+    The API and behavior may change in future releases.
+
+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.
+
+## Prerequisites
+
+* You have added a ClusterCatalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster.
+* The `GraphQLCatalogQueries` feature gate is enabled in catalogd.
+
+!!! note
+    By default, Catalogd is installed with TLS enabled for the catalog webserver.
+    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.
+
+You also need to port forward the catalog server service:
+
+``` terminal
+kubectl -n olmv1-system port-forward svc/catalogd-service 8443:443
+```
+
+## GraphQL Endpoint
+
+The GraphQL endpoint is available at:
+
+```
+https://localhost:8443/catalogs/<catalog-name>/api/v1/graphql
+```
+
+All queries must be sent as **HTTP POST** requests with a JSON body containing a `query` field.
+
+## Understanding GraphQL Field Names
+
+**IMPORTANT**: GraphQL field names are automatically generated from catalog schema names.
+
+### Naming Convention
+
+Schema names are converted to GraphQL field names using this process:
+
+1. Remove dots and special characters: `olm.bundle` → `olmbundle`
+2. Convert to lowercase: `OLM.Bundle` → `olmbundle`  
+3. Append 's' for pluralization: `olmbundle` → `olmbundles`
+
+**Examples:**
+
+| Schema Name | GraphQL Field Name |
+|-------------|-------------------|
+| `olm.bundle` | `olmbundles` |
+| `olm.package` | `olmpackages` |
+| `olm.channel` | `olmchannels` |
+| `helm.chart` | `helmcharts` |
+
+### Discovering Available Fields
+
+To find the exact field names available for your catalog, use GraphQL introspection:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ __schema { queryType { fields { name description } } } }"
+  }' | jq
+```
+
+This returns all available query fields for the catalog, including the automatically generated schema-based fields.
+
+!!! warning "Pluralization Limitations"
+    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.
+
+## Basic Queries
+
+### Catalog Summary
+
+Get an overview of schemas and object counts in the catalog:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ summary { totalSchemas schemas { name totalObjects totalFields } } }"
+  }' | jq
+```
+
+### Query Bundles
+
+List bundles with specific fields:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 5, offset: 0) { name package image } }"
+  }' | jq
+```
+
+### Query Packages
+
+List packages with metadata:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmpackages(limit: 10) { name description defaultChannel } }"
+  }' | jq
+```
+
+### Query Channels
+
+List channels:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmchannels { name package entries } }"
+  }' | jq
+```
+
+## Advanced Queries
+
+### Pagination
+
+All schema-based queries support pagination via `limit` and `offset` arguments:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 10, offset: 20) { name } }"
+  }' | jq
+```
+
+### Nested Field Selection
+
+Select only the fields you need, including array-nested objects:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmpackages { name channels { name entries { name } } } }"
+  }' | jq
+```
+
+**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:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmpackages { name icon } }"
+  }' | jq '.data.olmpackages[] | .icon | fromjson'
+```
+
+### Complex Bundle Properties
+
+Query bundle properties with their type and value fields:
+
+``` terminal
+curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ olmbundles(limit: 5) { name properties { type value } } }"
+  }' | jq
+```
+
+**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.
+
+## Comparing GraphQL vs Metas Endpoint
+
+| Feature | GraphQL (`/api/v1/graphql`) | Metas (`/api/v1/metas`) |
+|---------|---------------------------|------------------------|
+| Field selection | Precise - request only needed fields | All fields always returned |
+| Query complexity | Rich queries with nested objects | Simple parameter-based filtering |
+| Response size | Minimal - only requested data | Full objects always returned |
+| Schema discovery | Introspection built-in | External documentation needed |
+| Pagination | Built-in `limit` and `offset` | Manual implementation required |
+| HTTP Method | POST only | GET supported |
+| Feature status | Alpha (feature gate required) | Stable |
+
+**When to use GraphQL:**
+- You need specific fields from large objects
+- You want to query related data in a single request
+- You need structured, typed responses
+- You're building a UI or client that benefits from precise data fetching
+
+**When to use Metas endpoint:**
+- You need simple, stable API
+- You're doing basic filtering by schema/package/name
+- You want to use GET requests for caching
+- You need guaranteed API stability
+
+## Limitations
+
+1. **Pluralization**: Schema names are pluralized by appending 's', which may not be grammatically correct for all words
+2. **Schema naming**: Full schema names (including namespace/prefix) are preserved in field names (`olm.bundle` → `olmbundles`, not `bundles`)
+3. **POST only**: GraphQL endpoint only accepts POST requests, unlike the metas endpoint which supports GET
+4. **Alpha stability**: API may change in future releases while in alpha
+
+## Enabling the GraphQL Feature
+
+The GraphQL endpoint is controlled by the `GraphQLCatalogQueries` feature gate. To enable it:
+
+``` yaml
+args:
+  - --feature-gates=GraphQLCatalogQueries=true
+```
+
+See [enable webhook support](enable-webhook-support.md) for more details on configuring feature gates.
diff --git a/go.mod b/go.mod
@@ -7,7 +7,7 @@ require (
 	github.com/Masterminds/semver/v3 v3.5.0
 	github.com/blang/semver/v4 v4.0.0
 	github.com/cert-manager/cert-manager v1.20.2
-	github.com/containerd/containerd v1.7.31
+	github.com/containerd/containerd v1.7.32
 	github.com/cucumber/godog v0.15.1
 	github.com/evanphx/json-patch v5.9.11+incompatible
 	github.com/fsnotify/fsnotify v1.10.1
@@ -17,6 +17,7 @@ require (
 	github.com/google/go-containerregistry v0.21.5
 	github.com/google/renameio/v2 v2.0.2
 	github.com/gorilla/handlers v1.5.2
+	github.com/graphql-go/graphql v0.8.1
 	github.com/klauspost/compress v1.18.6
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.1
@@ -33,7 +34,7 @@ require (
 	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f
 	golang.org/x/mod v0.36.0
 	golang.org/x/sync v0.20.0
-	golang.org/x/tools v0.44.0
+	golang.org/x/tools v0.45.0
 	helm.sh/helm/v3 v3.21.0
 	k8s.io/api v0.35.4
 	k8s.io/apiextensions-apiserver v0.35.4
@@ -230,11 +231,11 @@ require (
 	go.podman.io/storage v1.62.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.4 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.50.0 // indirect
-	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
+	golang.org/x/net v0.54.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sys v0.44.0 // indirect
-	golang.org/x/term v0.42.0 // indirect
+	golang.org/x/term v0.43.0 // indirect
 	golang.org/x/text v0.37.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect

diff --git a/go.sum b/go.sum
@@ -59,8 +59,8 @@ github.com/clipperhouse/uax29/v2 v2.6.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsV
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/containerd/cgroups/v3 v3.1.2 h1:OSosXMtkhI6Qove637tg1XgK4q+DhR0mX8Wi8EhrHa4=
 github.com/containerd/cgroups/v3 v3.1.2/go.mod h1:PKZ2AcWmSBsY/tJUVhtS/rluX0b1uq1GmPO1ElCmbOw=
-github.com/containerd/containerd v1.7.31 h1:jn3IMuTV4Bb1Uwb0MFPW2ASJAD3W1lh6QqqZHIZwDh4=
-github.com/containerd/containerd v1.7.31/go.mod h1:jdwD6s/BhV4XVJGrvtziNPVA+83n66TwptVaPKprq4E=
+github.com/containerd/containerd v1.7.32 h1:S54xuVcPxeLaYgaRABtpJ2VyVUVsy0IGf7qHBs+sbY8=
+github.com/containerd/containerd v1.7.32/go.mod h1:jdwD6s/BhV4XVJGrvtziNPVA+83n66TwptVaPKprq4E=
 github.com/containerd/containerd/api v1.10.0 h1:5n0oHYVBwN4VhoX9fFykCV9dF1/BvAXeg2F8W6UYq1o=
 github.com/containerd/containerd/api v1.10.0/go.mod h1:NBm1OAk8ZL+LG8R0ceObGxT5hbUYj7CzTmR3xh0DlMM=
 github.com/containerd/continuity v0.4.5 h1:ZRoN1sXq9u7V6QoHMcVWGhOwDFqZ4B9i5H6un1Wh0x4=
@@ -280,6 +280,8 @@ github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5T
 github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
 github.com/gosuri/uitable v0.0.4 h1:IG2xLKRvErL3uhY6e1BylFzG+aJiwQviDDTfOKeKTpY=
 github.com/gosuri/uitable v0.0.4/go.mod h1:tKR86bXuXPZazfOTG1FIzvjIdXzd0mo4Vtn16vt0PJo=
+github.com/graphql-go/graphql v0.8.1 h1:p7/Ou/WpmulocJeEx7wjQy611rtXGQaAcXGqanuMMgc=
+github.com/graphql-go/graphql v0.8.1/go.mod h1:nKiHzRM0qopJEwCITUuIsxk9PlVlwIiiI8pnJEhordQ=
 github.com/gregjones/httpcache v0.0.0-20190611155906-901d90724c79 h1:+ngKgrYPPJrOjhax5N+uePQ0Fh1Z7PheYoUI/0nzkPA=
 github.com/gregjones/httpcache v0.0.0-20190611155906-901d90724c79/go.mod h1:FecbI9+v66THATjSRHfNgh1IVFe/9kFxbXtjV0ctIMA=
 github.com/grpc-ecosystem/go-grpc-prometheus v1.2.1-0.20210315223345-82c243799c99 h1:JYghRBlGCZyCF2wNUJ8W0cwaQdtpcssJ4CgC406g+WU=
@@ -603,8 +605,8 @@ golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliY
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M=
-golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
-golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f h1:W3F4c+6OLc6H2lb//N1q4WpJkhzJCK5J6kUi1NTVXfM=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f/go.mod h1:J1xhfL/vlindoeF/aINzNzt2Bket5bjo9sdOYzOsU80=
@@ -636,8 +638,8 @@ golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
+golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
@@ -682,8 +684,8 @@ golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
 golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
 golang.org/x/term v0.29.0/go.mod h1:6bl4lRlvVuDgSf3179VpIxBF0o10JUpXWOnI7nErv7s=
-golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
@@ -709,8 +711,8 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
-golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
 golang.org/x/tools/go/expect v0.1.1-deprecated h1:jpBZDwmgPhXsKZC6WhL20P4b/wmnpsEAGHaNy0n/rJM=
 golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY=
 golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated h1:1h2MnaIAIXISqTFKdENegdpAgUXz6NrPEsbIeWaBRvM=