From e935cff9820b94460ae028a035e67a3f7c14497e Mon Sep 17 00:00:00 2001 From: Anshul Gupta Date: Mon, 16 Nov 2026 07:39:21 +0000 Subject: [PATCH 1/3] serving-endpoints: add --json examples to help The generated help for create, update-config, put-ai-gateway, patch-telemetry-config and query only lists --json, and most of each request body has no flags. In agent trials, users of these commands guessed the body shape from errors or read the SDK source. Add one example body per command, each checked against the API, plus the AI Gateway field-removal behavior seen there. Co-authored-by: Isaac Signed-off-by: Anshul Gupta --- .../cli/serving-endpoints-help-examples.md | 1 + .../serving-endpoints/help_examples.go | 118 ++++++++++++++++++ .../serving-endpoints/help_examples_test.go | 39 ++++++ 3 files changed, 158 insertions(+) create mode 100644 .nextchanges/cli/serving-endpoints-help-examples.md create mode 100644 cmd/workspace/serving-endpoints/help_examples.go create mode 100644 cmd/workspace/serving-endpoints/help_examples_test.go diff --git a/.nextchanges/cli/serving-endpoints-help-examples.md b/.nextchanges/cli/serving-endpoints-help-examples.md new file mode 100644 index 00000000000..955bd3baa87 --- /dev/null +++ b/.nextchanges/cli/serving-endpoints-help-examples.md @@ -0,0 +1 @@ +* `serving-endpoints create`, `update-config`, `put-ai-gateway`, `patch-telemetry-config` and `query` now include example `--json` request bodies in their `--help`. diff --git a/cmd/workspace/serving-endpoints/help_examples.go b/cmd/workspace/serving-endpoints/help_examples.go new file mode 100644 index 00000000000..436fb1031c8 --- /dev/null +++ b/cmd/workspace/serving-endpoints/help_examples.go @@ -0,0 +1,118 @@ +package serving_endpoints + +import ( + "github.com/databricks/databricks-sdk-go/service/serving" + "github.com/spf13/cobra" +) + +// The generated help for these commands only lists --json, and most of their +// request body has no flags, so users and agents had to guess the JSON shape or +// read the SDK source. These examples were each checked against the API. + +const createExamples = ` + + Example: serve a Unity Catalog model version on CPU. + + databricks serving-endpoints create --json '{ + "name": "my-endpoint", + "config": { + "served_entities": [{ + "entity_name": "main.default.my_model", + "entity_version": "1", + "workload_size": "Small", + "scale_to_zero_enabled": true + }] + } + }'` + +const updateConfigExamples = ` + + Example: serve two model versions with an 80/20 traffic split. Each route's + served_entity_name refers to a served entity's "name". + + databricks serving-endpoints update-config my-endpoint --json '{ + "served_entities": [ + {"name": "v1", "entity_name": "main.default.my_model", "entity_version": "1", + "workload_size": "Small", "scale_to_zero_enabled": true}, + {"name": "v2", "entity_name": "main.default.my_model", "entity_version": "2", + "workload_size": "Small", "scale_to_zero_enabled": true} + ], + "traffic_config": {"routes": [ + {"served_entity_name": "v1", "traffic_percentage": 80}, + {"served_entity_name": "v2", "traffic_percentage": 20} + ]} + }'` + +const putAiGatewayExamples = ` + + Example: usage tracking, an inference table, a per-user rate limit and a PII + input guardrail. Settings left out of the request are removed, except + inference_table_config: to turn the inference table off, send it with + "enabled": false. Guardrails are only supported on some endpoint types, such + as external models. + + databricks serving-endpoints put-ai-gateway my-endpoint --json '{ + "usage_tracking_config": {"enabled": true}, + "inference_table_config": { + "enabled": true, + "catalog_name": "main", + "schema_name": "default", + "table_name_prefix": "my_endpoint" + }, + "rate_limits": [{"calls": 10, "key": "user", "renewal_period": "minute"}], + "guardrails": {"input": {"pii": {"behavior": "BLOCK"}}} + }'` + +const patchTelemetryConfigExamples = ` + + Example: export logs, traces and metrics to Unity Catalog tables. Leave out + enabled_telemetry_features to enable all of them. + + databricks serving-endpoints patch-telemetry-config my-endpoint --json '{ + "telemetry_config": { + "enabled_telemetry_features": [ + "TELEMETRY_FEATURE_LOGS", + "TELEMETRY_FEATURE_TRACES", + "TELEMETRY_FEATURE_METRICS" + ], + "table_names": { + "logs_table": "main.default.my_endpoint_logs", + "traces_table": "main.default.my_endpoint_traces", + "metrics_table": "main.default.my_endpoint_metrics" + } + } + }'` + +const queryExamples = ` + + Examples: the request body depends on the endpoint. + + # A custom model, one row per record (column names from the model signature) + databricks serving-endpoints query my-endpoint --json '{"dataframe_records": [{"x": 1.0, "y": 2.0}]}' + + # The same rows in split format + databricks serving-endpoints query my-endpoint --json '{"dataframe_split": {"columns": ["x", "y"], "data": [[1.0, 2.0]]}}' + + # Tensor input + databricks serving-endpoints query my-endpoint --json '{"inputs": [[1.0, 2.0]]}' + + # A chat model + databricks serving-endpoints query my-chat-endpoint --json '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}' + + Use "serving-endpoints get-open-api NAME" to see the request schema of an + endpoint.` + +// appendHelp returns an override that appends text to a command's help. +func appendHelp[T any](text string) func(*cobra.Command, T) { + return func(cmd *cobra.Command, _ T) { + cmd.Long += text + } +} + +func init() { + createOverrides = append(createOverrides, appendHelp[*serving.CreateServingEndpoint](createExamples)) + updateConfigOverrides = append(updateConfigOverrides, appendHelp[*serving.EndpointCoreConfigInput](updateConfigExamples)) + putAiGatewayOverrides = append(putAiGatewayOverrides, appendHelp[*serving.PutAiGatewayRequest](putAiGatewayExamples)) + patchTelemetryConfigOverrides = append(patchTelemetryConfigOverrides, appendHelp[*serving.PatchTelemetryConfigRequest](patchTelemetryConfigExamples)) + queryOverrides = append(queryOverrides, appendHelp[*serving.QueryEndpointInput](queryExamples)) +} diff --git a/cmd/workspace/serving-endpoints/help_examples_test.go b/cmd/workspace/serving-endpoints/help_examples_test.go new file mode 100644 index 00000000000..afa19ad3de5 --- /dev/null +++ b/cmd/workspace/serving-endpoints/help_examples_test.go @@ -0,0 +1,39 @@ +package serving_endpoints + +import ( + "encoding/json" + "regexp" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// Every example's --json body must be valid JSON, so users can copy it as is. +func TestHelpExamplesAreValidJSON(t *testing.T) { + body := regexp.MustCompile(`(?s)--json '(.*?)'`) + for name, text := range map[string]string{ + "create": createExamples, + "update-config": updateConfigExamples, + "put-ai-gateway": putAiGatewayExamples, + "patch-telemetry-config": patchTelemetryConfigExamples, + "query": queryExamples, + } { + t.Run(name, func(t *testing.T) { + matches := body.FindAllStringSubmatch(text, -1) + require.NotEmpty(t, matches) + for _, m := range matches { + assert.True(t, json.Valid([]byte(m[1])), "invalid JSON: %s", m[1]) + } + }) + } +} + +func TestNewCommandHelpIncludesExamples(t *testing.T) { + cmd := New() + for _, sub := range []string{"create", "update-config", "put-ai-gateway", "patch-telemetry-config", "query"} { + c, _, err := cmd.Find([]string{sub}) + require.NoError(t, err) + assert.Contains(t, c.Long, "Example", sub) + } +} From 4fa74dc85796d9f2c0c247f235275d1faed11b94 Mon Sep 17 00:00:00 2001 From: Anshul Gupta Date: Mon, 16 Nov 2026 07:39:34 +0000 Subject: [PATCH 2/3] Point changelog fragment at #7666 Co-authored-by: Isaac Signed-off-by: Anshul Gupta --- .nextchanges/cli/serving-endpoints-help-examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.nextchanges/cli/serving-endpoints-help-examples.md b/.nextchanges/cli/serving-endpoints-help-examples.md index 955bd3baa87..7f7017d3bd4 100644 --- a/.nextchanges/cli/serving-endpoints-help-examples.md +++ b/.nextchanges/cli/serving-endpoints-help-examples.md @@ -1 +1 @@ -* `serving-endpoints create`, `update-config`, `put-ai-gateway`, `patch-telemetry-config` and `query` now include example `--json` request bodies in their `--help`. +* `serving-endpoints create`, `update-config`, `put-ai-gateway`, `patch-telemetry-config` and `query` now include example `--json` request bodies in their `--help`. ([#7666](https://github.com/databricks/cli/pull/7666)) From 2809158bf0403f4044dd7494c9056014e9c63342 Mon Sep 17 00:00:00 2001 From: Anshul Gupta Date: Tue, 17 Nov 2026 00:10:04 +0000 Subject: [PATCH 3/3] Add a named-column inputs example to query help The tensor-only inputs example failed for models with a column signature, which reject a bare 2-D array. Checked against an MLflow scoring server. Co-authored-by: Isaac Signed-off-by: Anshul Gupta --- cmd/workspace/serving-endpoints/help_examples.go | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cmd/workspace/serving-endpoints/help_examples.go b/cmd/workspace/serving-endpoints/help_examples.go index 436fb1031c8..6505267d616 100644 --- a/cmd/workspace/serving-endpoints/help_examples.go +++ b/cmd/workspace/serving-endpoints/help_examples.go @@ -93,7 +93,10 @@ const queryExamples = ` # The same rows in split format databricks serving-endpoints query my-endpoint --json '{"dataframe_split": {"columns": ["x", "y"], "data": [[1.0, 2.0]]}}' - # Tensor input + # The same rows as "inputs", keyed by column name + databricks serving-endpoints query my-endpoint --json '{"inputs": {"x": [1.0], "y": [2.0]}}' + + # A model with a tensor signature (no column names) databricks serving-endpoints query my-endpoint --json '{"inputs": [[1.0, 2.0]]}' # A chat model