bigquery-data-science 0.7.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bigquery_data_science/__init__.py +58 -0
- bigquery_data_science/_skills/PLANS.md +76 -0
- bigquery_data_science/_skills/bigquery-ai/SKILL.md +66 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_agg.md +528 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_classify.md +450 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_count_tokens.md +180 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_detect_anomalies.md +322 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_embed.md +425 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_evaluate.md +368 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_forecast.md +437 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate.md +693 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_bool.md +248 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_double.md +254 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_embedding.md +402 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_int.md +252 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_table.md +447 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_text.md +356 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_if.md +373 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_key_drivers.md +331 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_parse_document.md +416 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_predict.md +559 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_score.md +310 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_search.md +465 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ai_similarity.md +371 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/catalog_search.md +951 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/content_analysis.md +284 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/content_moderation.md +369 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/data_enrichment.md +426 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/document_intelligence.md +470 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/document_rag.md +453 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/image_deduplication.md +770 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/log_analysis.md +668 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/metric_diagnostics.md +568 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_annotate_image.md +680 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_generate_embedding.md +217 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_generate_text.md +223 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_process_document.md +392 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_transcribe.md +815 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_translate.md +600 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/ml_understand_text.md +673 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/multimodal_analysis.md +266 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/rag_pipeline.md +593 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/semantic_search.md +510 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/tabular_prediction.md +485 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/time_series_intelligence.md +489 -0
- bigquery_data_science/_skills/bigquery-ai/narrative/vector_search.md +672 -0
- bigquery_data_science/_skills/bigquery-ai/reference/augmented-analytics.md +77 -0
- bigquery_data_science/_skills/bigquery-ai/reference/cloud-ai-service-models.md +88 -0
- bigquery_data_science/_skills/bigquery-ai/reference/document-processing.md +95 -0
- bigquery_data_science/_skills/bigquery-ai/reference/embeddings-and-search.md +166 -0
- bigquery_data_science/_skills/bigquery-ai/reference/general-purpose-generation.md +87 -0
- bigquery_data_science/_skills/bigquery-ai/reference/managed-functions.md +72 -0
- bigquery_data_science/_skills/bigquery-ai/reference/predictive-ai.md +113 -0
- bigquery_data_science/_skills/bigquery-ai/reference/workflows.md +56 -0
- bigquery_data_science/_skills/bigquery-ai/skill.manifest.json +109 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/INDEX.md +71 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiagg.md +67 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aicausal_effect-covered-in-bigquery-ml.md +17 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiclassify.md +72 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aicount_tokens.md +53 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aidetect_anomalies.md +63 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiembed.md +85 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aievaluate.md +114 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiforecast.md +123 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate.md +69 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_bool.md +53 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_double.md +45 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_embedding.md +108 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_int.md +45 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_table.md +64 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_text.md +167 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiif.md +56 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aikey_drivers.md +76 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiparse_document.md +91 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aipredict.md +74 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aiscore.md +52 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aisearch.md +66 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/aisimilarity.md +79 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/choosing-between-these-and-the-ai-functions.md +11 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/hybrid-search-capability.md +165 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mlannotate_image.md +24 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mlgenerate_embedding.md +34 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mlgenerate_text.md +65 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mlprocess_document.md +125 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mltranscribe.md +26 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mltranslate.md +27 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/mlunderstand_text.md +32 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/multimodal-input-patterns-by-function.md +128 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/object-tables.md +109 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objectref-and-objectrefruntime-schema-reference.md +50 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objfetch_metadata.md +49 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objget_access_url.md +66 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objget_read_url.md +40 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objlist.md +34 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/objmake_ref.md +58 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/per-row-failures-and-the-retry-pattern.md +19 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/setup-apis-connection-roles.md +39 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/two-input-shapes.md +22 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/vector_search.md +78 -0
- bigquery_data_science/_skills/bigquery-ai/syntax/what-the-five-have-in-common.md +27 -0
- bigquery_data_science/_skills/bigquery-data-science/SKILL.md +69 -0
- bigquery_data_science/_skills/bigquery-data-science/reference/namespace-matrix.md +112 -0
- bigquery_data_science/_skills/bigquery-data-science/skill.manifest.json +13 -0
- bigquery_data_science/_skills/bigquery-ml/SKILL.md +70 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/airflow_with_kfp.md +379 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/anomaly_fraud_detection.md +195 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/arima_plus.md +635 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/arima_plus_xreg.md +453 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/autoencoder.md +470 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/automl_classifier.md +291 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/automl_regressor.md +274 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/boosted_tree_classifier.md +449 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/boosted_tree_regressor.md +400 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/bucketizing.md +201 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/causal_effect.md +773 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/churn_retention.md +271 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/cloud_workflows.md +370 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/composer_airflow.md +475 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/contribution_analysis.md +346 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/cross_validation.md +185 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/customer_segmentation.md +233 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/dataform.md +372 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/dbt.md +283 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/difference_in_differences.md +280 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/distance.md +195 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/dnn_classifier.md +326 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/dnn_regressor.md +308 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/embeddings_classification.md +426 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/encoding.md +238 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/ensembling.md +278 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/evaluation.md +445 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/exploration.md +779 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/export.md +321 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/feature_engineering.md +280 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/feature_store.md +652 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/feature_store_workflow.md +426 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/ga4_churn_prediction.md +285 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/hierarchical_forecasting.md +441 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/image.md +791 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/imported.md +426 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/kmeans.md +348 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/linear_regression.md +372 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/logistic_regression.md +390 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/matrix_factorization.md +404 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/model_monitoring.md +609 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/pca.md +357 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/price_elasticity_dml.md +286 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/propensity_score_matching.md +350 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/random_forest_classifier.md +445 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/random_forest_regressor.md +409 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/recommendation.md +281 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/regression_based_forecasting.md +491 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/remote.md +428 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/scalers.md +325 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/scheduled_queries.md +284 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/sql_scripting.md +243 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/survival_analysis.md +363 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/synthetic_control.md +221 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/text.md +215 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/time_series.md +669 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/transform_only.md +273 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/uplift_cate.md +241 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/vertex_kfp.md +360 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/wide_and_deep_classifier.md +316 -0
- bigquery_data_science/_skills/bigquery-ml/narrative/wide_and_deep_regressor.md +298 -0
- bigquery_data_science/_skills/bigquery-ml/reference/classification.md +80 -0
- bigquery_data_science/_skills/bigquery-ml/reference/model-management.md +90 -0
- bigquery_data_science/_skills/bigquery-ml/reference/preprocessing-functions.md +234 -0
- bigquery_data_science/_skills/bigquery-ml/reference/regression.md +79 -0
- bigquery_data_science/_skills/bigquery-ml/reference/unsupervised-and-specialized.md +101 -0
- bigquery_data_science/_skills/bigquery-ml/reference/workflows-and-pipelines.md +111 -0
- bigquery_data_science/_skills/bigquery-ml/skill.manifest.json +177 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/1-model_type-catalog.md +28 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/2-task-mlevaluate-metric-columns.md +26 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/3-capability-matrix-per-model-type.md +21 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/4-explainability-weights-functions.md +14 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/5-connection-matrix.md +11 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/6-which-model-free-function-no-create-model-no-connection.md +15 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/7-point-in-time-feature-retrieval-which-of-the-two.md +11 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/INDEX.md +111 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/aicausal_effect.md +85 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus-forecasting-lifecycle-functions.md +14 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus-univariate-time-series-forecasting.md +132 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus_xreg-multivariate-time-series-with-external-regressors.md +103 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/autoencoder.md +102 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/automl_classifier-automl_regressor.md +88 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/boosted_tree_classifier-boosted_tree_regressor.md +117 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/contribution_analysis.md +113 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/dnn_classifier-dnn_regressor.md +107 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/dnn_linear_combined_classifier-dnn_linear_combined_regressor-wide-and-deep.md +98 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/explainability-functions-mlexplain_predict-mlglobal_explain-mlfeature_importance.md +7 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/exploratory-data-analysis-mldescribe_data-mlcorrelation.md +11 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/export-model.md +92 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/feature-engineering-standalone-preprocessing-functions.md +13 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/image-preprocessing-functions-mldecode_image-mlresize_image-mlconvert_image_type-mlconvert_color_space.md +63 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/imported-models-tensorflow-tensorflow_lite-onnx-xgboost.md +36 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/kmeans.md +87 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/linear_reg-logistic_reg-generalized-linear-models.md +101 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/matrix_factorization.md +162 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mladvanced_weights.md +76 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlarima_coefficients.md +30 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlarima_evaluate.md +49 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlbag_of_words.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlbucketize.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlcentroids.md +46 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlconfusion_matrix.md +56 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlconvert_color_space.md +53 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlconvert_image_type.md +39 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlcorrelation.md +78 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mldecode_image.md +44 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mldescribe_data.md +74 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mldetect_anomalies.md +86 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mldistance.md +48 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlentity_features_at_time.md +56 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlevaluate.md +72 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlexplain_forecast.md +50 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlexplain_predict.md +66 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_cross.md +46 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_importance.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_info.md +50 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlfeatures_at_time.md +51 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlforecast.md +76 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlgenerate_embedding-from-a-bqml-pca-autoencoder-matrix_factorization-model.md +64 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlglobal_explain.md +63 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlhash_bucketize.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlholiday_info.md +46 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlimputer.md +46 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mllp_norm.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlmetrics.md +80 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlngrams.md +37 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlone_hot_encoder-mlmulti_hot_encoder-mllabel_encoder.md +67 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlpolynomial_expand.md +47 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlpredict.md +67 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlprincipal_component_info.md +42 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlprincipal_components.md +40 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlquantile_bucketize.md +43 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlrecommend.md +60 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlreconstruction_loss.md +48 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlresize_image.md +45 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlroc_curve.md +63 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltf_idf.md +37 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltfdv_describe.md +34 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltfdv_validate.md +48 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltraining_info.md +78 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltransform-applying-a-saved-transform.md +52 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltranspose-not-a-function-pointer.md +32 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mltrial_info.md +60 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlvalidate_data_drift.md +99 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlvalidate_data_skew.md +50 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/mlweights.md +84 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/model-free-time-series-decomposition-mltrend-mlseasonality-mldetect_change_points.md +100 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/model-introspection-mlfeature_info-mltraining_info-mltrial_info.md +7 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/model-monitoring-data-validation.md +23 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/numerical-scalers-mlstandard_scaler-mlmin_max_scaler-mlmax_abs_scaler-mlrobust_scaler-mlnormalizer.md +77 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/onnx.md +55 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/pca.md +91 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/point-in-time-feature-retrieval-mlfeatures_at_time-mlentity_features_at_time.md +25 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/quick-comparison.md +14 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/random_forest_classifier-random_forest_regressor.md +123 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/remote-remote-model-over-a-vertex-ai-endpoint-the-mechanism.md +87 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/tensorflow.md +48 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/tensorflow_lite.md +29 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/text-preprocessing-functions-mlngrams-mltf_idf-mlbag_of_words.md +18 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/timesfm-built-in-foundation-forecaster-see-bigquery-ai.md +28 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/transform_only.md +91 -0
- bigquery_data_science/_skills/bigquery-ml/syntax/xgboost.md +72 -0
- bigquery_data_science/_skills/pinned-models.json +28 -0
- bigquery_data_science/catalog.py +1107 -0
- bigquery_data_science/cli.py +786 -0
- bigquery_data_science/installer.py +282 -0
- bigquery_data_science/mcp_server.py +317 -0
- bigquery_data_science/tooling/__init__.py +15 -0
- bigquery_data_science/tooling/convert_notebook.py +176 -0
- bigquery_data_science/tooling/link_policy.py +247 -0
- bigquery_data_science/tooling/manifest.py +152 -0
- bigquery_data_science/tooling/markdown_anchors.py +84 -0
- bigquery_data_science/tooling/narrative_drift.py +163 -0
- bigquery_data_science/tooling/pinned_models.py +216 -0
- bigquery_data_science/tooling/reference_structure.py +85 -0
- bigquery_data_science/tooling/sync_syntax.py +407 -0
- bigquery_data_science/tooling/validate.py +208 -0
- bigquery_data_science-0.7.0.dist-info/METADATA +306 -0
- bigquery_data_science-0.7.0.dist-info/RECORD +286 -0
- bigquery_data_science-0.7.0.dist-info/WHEEL +4 -0
- bigquery_data_science-0.7.0.dist-info/entry_points.txt +5 -0
- bigquery_data_science-0.7.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,791 @@
|
|
|
1
|
+
> **Source (`statmike/bigquery-data-science`):** **Notebook:** [`bigquery-ml/functions/image/image.ipynb`](https://github.com/statmike/bigquery-data-science/blob/main/bigquery-ml/functions/image/image.ipynb) · **SQL:** [`bigquery-ml/functions/image/image.sql`](https://github.com/statmike/bigquery-data-science/blob/main/bigquery-ml/functions/image/image.sql)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
# Image Preprocessing — `ML.DECODE_IMAGE`, `ML.RESIZE_IMAGE`, `ML.CONVERT_COLOR_SPACE`, `ML.CONVERT_IMAGE_TYPE`
|
|
5
|
+
|
|
6
|
+
Four model-free scalar functions that turn image **bytes** into the numeric `STRUCT` a vision model consumes: decode, resize, change color space, quantize to integers. They train nothing, create no model object, and nest freely inside one another and inside a `TRANSFORM` clause.
|
|
7
|
+
|
|
8
|
+
They are also the least accurately documented family in this project, which is most of what this notebook is for. Everything below is measured here, against images this notebook builds pixel by pixel, so every claim has a cell you can read.
|
|
9
|
+
|
|
10
|
+
> **GOTCHA — these four functions require a BigQuery Editions reservation.** On-demand (per-byte) pricing fails outright. Setup demonstrates the exact error, then creates a small autoscaling `ENTERPRISE` reservation and deletes it in Cleanup. **None of the four official reference pages mentions this.** `MATRIX_FACTORIZATION` (`models/matrix_factorization` (`models/matrix_factorization/`)) is the only other thing in this project with the same requirement.
|
|
11
|
+
|
|
12
|
+
**What this notebook establishes, all measured here rather than quoted:**
|
|
13
|
+
|
|
14
|
+
1. The output `STRUCT`'s fields are named **`dimensions`** and **`values`** — not `shape`.
|
|
15
|
+
2. `ML.DECODE_IMAGE` takes **any** `BYTES` value, not only an object table's `data` pseudocolumn. That is what makes the rest of this notebook reproducible without a bucket.
|
|
16
|
+
3. **Decoding always returns 3 channels**, whatever the source had — an RGBA image's alpha is silently dropped (not composited), and a single-channel grayscale image is replicated into three identical channels. `ML.CONVERT_COLOR_SPACE(..., 'GRAYSCALE')` then takes it back down to **1**, so the channel count is set by the last function in the chain, not by the image.
|
|
17
|
+
4. The `[0, 1)` and `[0, 255)` ranges printed on the reference pages are wrong at the top end — a pure-white pixel is exactly `1.0`, and `ML.CONVERT_IMAGE_TYPE` returns exactly `255`.
|
|
18
|
+
5. `ML.CONVERT_IMAGE_TYPE` is **one-way**: there is no integer→float signature.
|
|
19
|
+
6. `GRAYSCALE` and `YIQ`'s Y channel are **two different lumas**, differing in the fourth decimal place.
|
|
20
|
+
7. `ML.RESIZE_IMAGE` is **type-preserving and float32**, while decode and color-space conversion are float64-exact.
|
|
21
|
+
8. A `preserve_aspect_ratio = TRUE` fit that rounds a dimension to zero raises an **internal error the client library retries for minutes** unless you turn job retry off.
|
|
22
|
+
9. All four are **TensorFlow image ops**. Diffed against TensorFlow directly: `HSV`, bilinear resize and the integer conversion are **bit-exact**, `YIQ`/`YUV` match to a last-place unit of a double, and the one row that misses at single precision misses because **`tf.image` computes it in float32 while BigQuery uses double**.
|
|
23
|
+
|
|
24
|
+
**When to use these:** you have image bytes in Cloud Storage and a vision model — `models/imported` (imported) or `models/remote` (remote) — that expects a fixed-size numeric tensor. These four get you from one to the other in SQL, with no data leaving BigQuery. For *generative* work on images (captioning, classification by prompt, embeddings) the path is entirely different — see **Related content** below.
|
|
25
|
+
|
|
26
|
+
**Data:** six images this notebook constructs from NumPy arrays — small enough that every pixel value is printable and checkable by hand, which is the only way the precision findings above are provable. They are uploaded to Cloud Storage so Step 8 can exercise the real object-table path.
|
|
27
|
+
|
|
28
|
+
**Related content:** `models/imported` (`models/imported/`) — how the model these features feed gets into BigQuery. `models/matrix_factorization` (`models/matrix_factorization/`) — the same reservation pattern, for the same reason. For multimodal generative AI over images (`ML.GENERATE_TEXT`, `AI.GENERATE_TABLE`, `ML.GENERATE_EMBEDDING` over an ObjectRef), see the sibling project `bigquery-ai` (`bigquery-ai`) — that is a foundation-model path, not this preprocessing one.
|
|
29
|
+
|
|
30
|
+
**References:** `reference/model-free-functions.md` (Full reference) | [ML.DECODE_IMAGE](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-decode-image) | [ML.RESIZE_IMAGE](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-resize-image) | [ML.CONVERT_COLOR_SPACE](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-convert-color-space) | [ML.CONVERT_IMAGE_TYPE](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-convert-image-type) | [Object tables](https://cloud.google.com/bigquery/docs/object-tables) | `setup` (Setup guide)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
## Setup
|
|
35
|
+
|
|
36
|
+
Set your project, location, and bucket, authenticate, create the shared dataset — then deal with the reservation requirement, which is the part no other `functions/` notebook has.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
PROJECT_ID = 'statmike-mlops-349915' # <-- Replace with your project ID
|
|
40
|
+
LOCATION = 'US' # BigQuery dataset location
|
|
41
|
+
DATASET_ID = 'bq_ml' # Shared dataset across all bigquery-ml notebooks
|
|
42
|
+
BUCKET = 'statmike-mlops-349915' # <-- Replace with your GCS bucket (same location as DATASET_ID)
|
|
43
|
+
CONNECTION_ID = 'bq_ml_image_demo' # Cloud Resource Connection for the object table in Step 8
|
|
44
|
+
RESERVATION_ID = 'bqml-image-temp' # Temporary reservation name (Setup creates it, Cleanup removes it)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
### Environment
|
|
49
|
+
|
|
50
|
+
> **Already set up the project environment?** The cell below is a no-op — packages are already in your kernel. See the `setup` (Setup Reference) for details.
|
|
51
|
+
>
|
|
52
|
+
> **Running standalone** (Colab, Colab Enterprise, Vertex AI Workbench)? The cell below installs required packages into your current kernel.
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
from google.cloud import bigquery, storage
|
|
56
|
+
import pandas as pd
|
|
57
|
+
|
|
58
|
+
client = bigquery.Client(project=PROJECT_ID)
|
|
59
|
+
gcs_client = storage.Client(project=PROJECT_ID)
|
|
60
|
+
gcs_bucket = gcs_client.bucket(BUCKET)
|
|
61
|
+
pd.set_option('display.max_colwidth', None)
|
|
62
|
+
|
|
63
|
+
# Every image query in this notebook runs cache-off. The reservation demo two cells
|
|
64
|
+
# below depends on it: a cached result is served without slots and would hide the
|
|
65
|
+
# very failure the cell exists to show.
|
|
66
|
+
no_cache = bigquery.QueryJobConfig(use_query_cache=False)
|
|
67
|
+
|
|
68
|
+
# Create the shared dataset (idempotent)
|
|
69
|
+
dataset_ref = bigquery.DatasetReference(PROJECT_ID, DATASET_ID)
|
|
70
|
+
dataset = bigquery.Dataset(dataset_ref)
|
|
71
|
+
dataset.location = LOCATION
|
|
72
|
+
client.create_dataset(dataset, exists_ok=True)
|
|
73
|
+
print(f'Dataset {PROJECT_ID}.{DATASET_ID} ready')
|
|
74
|
+
|
|
75
|
+
# Register %%bigquery cell magic (auto-loaded in Colab, needed elsewhere)
|
|
76
|
+
%load_ext bigquery_magics
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
### Build the test images
|
|
81
|
+
|
|
82
|
+
Six images, defined as NumPy arrays so the ground truth is in the notebook rather than in a file. Two pixels carry most of the weight: **(200, 100, 50)**, a warm color with all three channels distinct, and **(0, 128, 255)**, which pins the low end, the middle, and the high end at once.
|
|
83
|
+
|
|
84
|
+
Each is encoded to PNG (and one to JPEG) in memory. The bytes are kept two ways: base64, so they can be inlined into SQL as a `BYTES` literal, and raw, so Step 8 can upload them to Cloud Storage.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import io, base64
|
|
88
|
+
import numpy as np
|
|
89
|
+
from PIL import Image
|
|
90
|
+
|
|
91
|
+
# Ground truth, as arrays. Shape is (height, width, channels).
|
|
92
|
+
swatch_a = np.array([[[200, 100, 50], [0, 128, 255]]], dtype=np.uint8) # 1x2 RGB
|
|
93
|
+
gradient_a = np.array([[[x * 32, y * 64, 128] for x in range(8)] for y in range(4)], np.uint8) # 4x8 RGB
|
|
94
|
+
alpha_a = np.array([[[200, 100, 50, 255], [0, 128, 255, 128]]], dtype=np.uint8) # 1x2 RGBA
|
|
95
|
+
white_a = np.array([[[255, 255, 255]]], dtype=np.uint8) # 1x1 RGB
|
|
96
|
+
|
|
97
|
+
def encode(array, fmt='PNG', mode=None):
|
|
98
|
+
image = Image.fromarray(array)
|
|
99
|
+
if mode:
|
|
100
|
+
image = image.convert(mode)
|
|
101
|
+
buffer = io.BytesIO()
|
|
102
|
+
image.save(buffer, format=fmt)
|
|
103
|
+
return buffer.getvalue()
|
|
104
|
+
|
|
105
|
+
raw = {
|
|
106
|
+
'swatch.png': encode(swatch_a),
|
|
107
|
+
'gradient.png': encode(gradient_a),
|
|
108
|
+
'alpha.png': encode(alpha_a),
|
|
109
|
+
'gray.png': encode(swatch_a, mode='L'), # single-channel PNG
|
|
110
|
+
'white.png': encode(white_a),
|
|
111
|
+
'swatch.jpg': encode(swatch_a, fmt='JPEG'),
|
|
112
|
+
}
|
|
113
|
+
b64 = {name: base64.b64encode(data).decode() for name, data in raw.items()}
|
|
114
|
+
|
|
115
|
+
def img(name):
|
|
116
|
+
"""SQL fragment: this image's bytes as a literal, decoded."""
|
|
117
|
+
return f"ML.DECODE_IMAGE(FROM_BASE64('{b64[name]}'))"
|
|
118
|
+
|
|
119
|
+
for name, data in raw.items():
|
|
120
|
+
print(f'{name:14s} {len(data):5d} bytes')
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
### The undocumented prerequisite: a slot reservation
|
|
125
|
+
|
|
126
|
+
The cell below runs the simplest possible `ML.DECODE_IMAGE` call under whatever pricing model this project currently has. On a project with no reservation, it fails.
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from google.api_core.exceptions import BadRequest
|
|
130
|
+
|
|
131
|
+
probe = f'SELECT {img("swatch.png")}.dimensions AS dims'
|
|
132
|
+
try:
|
|
133
|
+
print('On-demand result:', list(client.query(probe, job_config=no_cache).result())[0]['dims'])
|
|
134
|
+
print('\nThis project already has a reservation assigned — the next cell will reuse or create one anyway.')
|
|
135
|
+
except BadRequest as e:
|
|
136
|
+
print('On-demand FAILED, as expected:\n')
|
|
137
|
+
print(str(e).split(';')[0])
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
That message names the requirement precisely — `job type QUERY`, this project or its parent, this location — and it appears on none of the four function reference pages, nor on the [manual preprocessing](https://cloud.google.com/bigquery/docs/manual-preprocessing) or [object table inference](https://cloud.google.com/bigquery/docs/object-table-inference) pages that tell you to use these functions.
|
|
141
|
+
|
|
142
|
+
The fix is a BigQuery Editions reservation. This notebook creates a small **autoscaling `ENTERPRISE`** one — 0 baseline slots, scaling to 100 only while a query actually runs — and deletes it in Cleanup.
|
|
143
|
+
|
|
144
|
+
> **This is not a capacity commitment.** No upfront purchase, no minimum term. It bills per-second for slot-time actually consumed and idles at zero cost. Do not substitute a commitment for it.
|
|
145
|
+
|
|
146
|
+
**Idempotent:** re-running detects and reuses an existing reservation/assignment instead of erroring or duplicating.
|
|
147
|
+
|
|
148
|
+
> **Assignment propagation is not atomic, so this cell waits on evidence rather than on a clock.** A probe query can succeed and the very next query — seconds later, same session, same project — fail again with the identical "no reservation was assigned" error. That rules out both a fixed sleep and a single successful probe as evidence, so the loop below requires several consecutive successes before continuing. How long it takes is not fixed either: watch the elapsed times it prints.
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
import time
|
|
152
|
+
from google.cloud import bigquery_reservation_v1
|
|
153
|
+
from google.api_core.exceptions import AlreadyExists
|
|
154
|
+
|
|
155
|
+
reservation_client = bigquery_reservation_v1.ReservationServiceClient()
|
|
156
|
+
reservation_parent = f'projects/{PROJECT_ID}/locations/{LOCATION}'
|
|
157
|
+
reservation_name = f'{reservation_parent}/reservations/{RESERVATION_ID}'
|
|
158
|
+
|
|
159
|
+
try:
|
|
160
|
+
reservation = reservation_client.create_reservation(
|
|
161
|
+
parent=reservation_parent,
|
|
162
|
+
reservation_id=RESERVATION_ID,
|
|
163
|
+
reservation=bigquery_reservation_v1.Reservation(
|
|
164
|
+
slot_capacity=0,
|
|
165
|
+
edition=bigquery_reservation_v1.Edition.ENTERPRISE,
|
|
166
|
+
autoscale=bigquery_reservation_v1.Reservation.Autoscale(max_slots=100),
|
|
167
|
+
ignore_idle_slots=True,
|
|
168
|
+
),
|
|
169
|
+
)
|
|
170
|
+
print(f'Created {reservation.name}')
|
|
171
|
+
except AlreadyExists:
|
|
172
|
+
reservation = reservation_client.get_reservation(name=reservation_name)
|
|
173
|
+
print(f'Reservation already exists — reusing {reservation.name}')
|
|
174
|
+
|
|
175
|
+
existing_assignments = list(reservation_client.list_assignments(parent=reservation.name))
|
|
176
|
+
if existing_assignments:
|
|
177
|
+
assignment = existing_assignments[0]
|
|
178
|
+
print(f'Assignment already exists — reusing {assignment.name}')
|
|
179
|
+
else:
|
|
180
|
+
assignment = reservation_client.create_assignment(
|
|
181
|
+
parent=reservation.name,
|
|
182
|
+
assignment=bigquery_reservation_v1.Assignment(
|
|
183
|
+
job_type=bigquery_reservation_v1.Assignment.JobType.QUERY,
|
|
184
|
+
assignee=f'projects/{PROJECT_ID}',
|
|
185
|
+
),
|
|
186
|
+
)
|
|
187
|
+
print(f'Created {assignment.name}')
|
|
188
|
+
|
|
189
|
+
# Wait for the reservation to answer CONSISTENTLY, not just once. A fixed sleep
|
|
190
|
+
# is not enough: one probe succeeded here and the next one failed.
|
|
191
|
+
required_streak, streak, waited = 3, 0, 0
|
|
192
|
+
while streak < required_streak:
|
|
193
|
+
try:
|
|
194
|
+
dims = list(client.query(probe, job_config=no_cache).result())[0]['dims']
|
|
195
|
+
streak += 1
|
|
196
|
+
print(f' probe {streak}/{required_streak} succeeded ({waited}s elapsed): {list(dims)}')
|
|
197
|
+
except BadRequest as e:
|
|
198
|
+
if 'requires reservation' not in str(e):
|
|
199
|
+
raise
|
|
200
|
+
streak = 0
|
|
201
|
+
print(f' not propagated yet ({waited}s elapsed)')
|
|
202
|
+
if streak < required_streak:
|
|
203
|
+
if waited >= 600:
|
|
204
|
+
raise RuntimeError('Reservation did not become usable within 10 minutes')
|
|
205
|
+
time.sleep(15)
|
|
206
|
+
waited += 15
|
|
207
|
+
|
|
208
|
+
print('Reservation is live.')
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
## Step 1 — What `ML.DECODE_IMAGE` actually returns
|
|
214
|
+
|
|
215
|
+
`[1, 2, 3]` from the cell above is already the first correction. The reference pages describe the output as `STRUCT<ARRAY<INT64> shape, ARRAY<FLOAT64> values>`. Select `.shape` and the query fails; the field is named **`dimensions`**.
|
|
216
|
+
|
|
217
|
+
Note also what the call above took as input: a `BYTES` literal built by `FROM_BASE64`. Every doc example passes an object table's `data` pseudocolumn, and the parameter is described as coming from one, but the signature is just `BYTES` — so the function is testable without a bucket, a connection, or an object table. Step 8 uses the object-table path for real; everything between here and there uses literals, which is why every value below is reproducible without any Cloud Storage setup.
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
query = f"""
|
|
221
|
+
SELECT {img('swatch.png')}.dimensions AS dimensions,
|
|
222
|
+
{img('swatch.png')}.values AS values
|
|
223
|
+
"""
|
|
224
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
225
|
+
h, w, c = row['dimensions']
|
|
226
|
+
print(f'dimensions = {list(row["dimensions"])} -> height={h}, width={w}, channels={c}')
|
|
227
|
+
print(f'values = {list(row["values"])}')
|
|
228
|
+
print(f'len(values) = {len(row["values"])} = {h} x {w} x {c}')
|
|
229
|
+
|
|
230
|
+
# Ground truth: the array this notebook built, flattened row-major, divided by 255.
|
|
231
|
+
expected = swatch_a.astype(np.float64).ravel() / 255.0
|
|
232
|
+
print(f'\nexpected = {list(expected)}')
|
|
233
|
+
print(f'max |BigQuery - expected| = {np.abs(np.array(row["values"]) - expected).max()}')
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Three parts of the contract, all confirmed:
|
|
237
|
+
|
|
238
|
+
- **`dimensions` is `[height, width, channels]`** — the 1×2 image gives `[1, 2, 3]`, so height leads.
|
|
239
|
+
- **`values` is flattened row-major in HWC order** — pixel 1's three channels, then pixel 2's. Not planar (all R, then all G, then all B), which is the other convention a vision model might want and which you would have to build yourself.
|
|
240
|
+
- **The scaling is exactly `pixel / 255`, with no rounding error at all.** The difference from the float64 ground truth is `0.0`, not a small epsilon. `200/255` came back as the correctly-rounded double.
|
|
241
|
+
|
|
242
|
+
That last point matters more than it looks: it means these values are exact enough to reason about, and it sets up the precision comparison in Step 6, where one of the four functions behaves differently.
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
## Step 2 — Decode always returns exactly 3 channels
|
|
247
|
+
|
|
248
|
+
The reference pages say the input may be JPEG, PNG, or BMP. They do not say what happens to the channel count when the source image is not 3-channel RGB. Two cases matter in practice — a PNG with an alpha channel, and a single-channel grayscale PNG — and they resolve in opposite directions.
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
query = f"""
|
|
252
|
+
SELECT {img('alpha.png')}.dimensions AS rgba_dimensions,
|
|
253
|
+
{img('alpha.png')}.values AS rgba_values,
|
|
254
|
+
{img('gray.png')}.dimensions AS gray_dimensions,
|
|
255
|
+
{img('gray.png')}.values AS gray_values
|
|
256
|
+
"""
|
|
257
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
258
|
+
|
|
259
|
+
print(f'Source alpha.png is RGBA, shape {alpha_a.shape}, pixels {alpha_a.reshape(-1, 4).tolist()}')
|
|
260
|
+
print(f' decoded dimensions: {list(row["rgba_dimensions"])}')
|
|
261
|
+
print(f' decoded x255: {[round(v * 255, 6) for v in row["rgba_values"]]}')
|
|
262
|
+
|
|
263
|
+
gray_source = np.array(Image.fromarray(swatch_a).convert('L'))
|
|
264
|
+
print(f'\nSource gray.png is single-channel L, shape {gray_source.shape}, pixels {gray_source.ravel().tolist()}')
|
|
265
|
+
print(f' decoded dimensions: {list(row["gray_dimensions"])}')
|
|
266
|
+
print(f' decoded x255: {[round(v * 255, 6) for v in row["gray_values"]]}')
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**Channels is always 3.** Both images decode to `channels = 3` regardless of what they contained.
|
|
270
|
+
|
|
271
|
+
- **The alpha channel is dropped, not applied.** The second pixel of `alpha.png` has alpha 128 — half transparent — and its RGB values come back as `0, 128, 255`, identical to the fully-opaque source values. Nothing was blended against a background and nothing was premultiplied. If your corpus mixes transparent PNGs with opaque ones, BigQuery will hand your model the raw RGB underneath the transparency, silently, and the two will not be comparable to whatever your training-time preprocessing did if that preprocessing composited. There is no flag to change this and no warning.
|
|
272
|
+
- **A grayscale image is replicated into three identical channels.** `gray.png` holds one value per pixel and decodes to that value three times. The size of a decoded feature vector therefore depends only on height and width, never on the source encoding — convenient for a fixed-shape model, and it means a mixed corpus of RGB, RGBA, and grayscale files needs no per-file branching. (This is a rule about *decoding*. Step 5 shows `ML.CONVERT_COLOR_SPACE(..., 'GRAYSCALE')` going the other way, back down to 1 channel.)
|
|
273
|
+
|
|
274
|
+
The format list is enforced at decode time, and the error names the accepted set:
|
|
275
|
+
|
|
276
|
+
```python
|
|
277
|
+
try:
|
|
278
|
+
client.query("SELECT ML.DECODE_IMAGE(b'not an image at all').dimensions", job_config=no_cache).result()
|
|
279
|
+
except BadRequest as e:
|
|
280
|
+
print(str(e).split(';')[0])
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
PNG, JPEG, BMP — no GIF, no WEBP, no TIFF, no AVIF. An object table happily lists files of any type; the failure surfaces only when a row reaches `ML.DECODE_IMAGE`, which means one stray file in a bucket fails the whole query rather than that one row.
|
|
284
|
+
|
|
285
|
+
**JPEG decodes to different numbers than PNG for the same source image**, which is worth stating explicitly because it is easy to build a corpus in mixed formats and treat the results as comparable:
|
|
286
|
+
|
|
287
|
+
```python
|
|
288
|
+
query = f"""
|
|
289
|
+
SELECT ML.CONVERT_IMAGE_TYPE({img('swatch.png')}).values AS png_ints,
|
|
290
|
+
ML.CONVERT_IMAGE_TYPE({img('swatch.jpg')}).values AS jpg_ints
|
|
291
|
+
"""
|
|
292
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
293
|
+
print(f'source pixels : {swatch_a.reshape(-1, 3).tolist()}')
|
|
294
|
+
print(f'via PNG : {np.array(row["png_ints"]).reshape(-1, 3).tolist()}')
|
|
295
|
+
print(f'via JPEG : {np.array(row["jpg_ints"]).reshape(-1, 3).tolist()}')
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
PNG is lossless and round-trips the source exactly. JPEG does not, and on a 2-pixel image it is not close — JPEG's 8×8 DCT blocks and chroma subsampling have nothing to work with at this size, so the reconstruction is dominated by block averaging. A photograph would survive far better. The point stands either way: **the decoded feature vector is a property of the file, not of the picture**, so re-encoding a corpus changes your features.
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
## Step 3 — The documented value ranges are wrong at the top
|
|
303
|
+
|
|
304
|
+
Every reference page states the decoded range as `[0, 1)` and the `ML.CONVERT_IMAGE_TYPE` range as `[0, 255)`. Both are written half-open, excluding the upper bound. A pure-white pixel settles it.
|
|
305
|
+
|
|
306
|
+
```python
|
|
307
|
+
query = f"""
|
|
308
|
+
SELECT {img('white.png')}.values AS float_values,
|
|
309
|
+
ML.CONVERT_IMAGE_TYPE({img('white.png')}).values AS int_values,
|
|
310
|
+
{img('white.png')}.values[OFFSET(0)] = 1.0 AS float_is_exactly_one,
|
|
311
|
+
ML.CONVERT_IMAGE_TYPE({img('white.png')}).values[OFFSET(0)] = 255 AS int_is_exactly_255
|
|
312
|
+
"""
|
|
313
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
314
|
+
for k, v in row.items():
|
|
315
|
+
print(f'{k:22s} {list(v) if isinstance(v, list) else v}')
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Both endpoints are attainable. The decoded range is **`[0, 1]`** and the integer range is **`[0, 255]`**, both closed. The comparison is done in SQL rather than by eyeballing a printed `1.0`, because a float that prints as `1.0` need not equal `1.0`; this one does.
|
|
319
|
+
|
|
320
|
+
This is not pedantry. `[0, 255)` is how you would describe a range that a model's input validation should reject 255 from, and code written to that spec — a clamp, an assertion, a bucket boundary — is wrong on every white pixel, which is a common pixel.
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
## Step 4 — `ML.CONVERT_IMAGE_TYPE` is exact, and one-way
|
|
325
|
+
|
|
326
|
+
Its job is the float→integer direction for models that want `uint8` input. Round-tripping the swatch shows it is lossless in that direction:
|
|
327
|
+
|
|
328
|
+
```python
|
|
329
|
+
query = f'SELECT ML.CONVERT_IMAGE_TYPE({img("swatch.png")}).values AS ints'
|
|
330
|
+
ints = list(list(client.query(query, job_config=no_cache).result())[0]['ints'])
|
|
331
|
+
print(f'source : {swatch_a.ravel().tolist()}')
|
|
332
|
+
print(f'decoded -> converted back to int : {ints}')
|
|
333
|
+
print(f'identical: {ints == swatch_a.ravel().tolist()}')
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
`pixel / 255` then back is exact for all 256 byte values, so decode → convert is a safe round trip.
|
|
337
|
+
|
|
338
|
+
The reverse does not exist. Feeding integer image data back in is a signature error, not a runtime one — and the error text is the authoritative statement of the struct's real field names:
|
|
339
|
+
|
|
340
|
+
```python
|
|
341
|
+
query = f'SELECT ML.CONVERT_IMAGE_TYPE(ML.CONVERT_IMAGE_TYPE({img("swatch.png")})).values'
|
|
342
|
+
try:
|
|
343
|
+
client.query(query, job_config=no_cache).result()
|
|
344
|
+
except BadRequest as e:
|
|
345
|
+
print(str(e).split(';')[0])
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
`STRUCT<dimensions ARRAY<INT64>, values ARRAY<FLOAT64>>` in, `STRUCT<dimensions ARRAY<INT64>, values ARRAY<INT64>>` out. `dimensions`, from the engine itself.
|
|
349
|
+
|
|
350
|
+
The practical consequence: **`ML.CONVERT_IMAGE_TYPE` is terminal.** Once converted, the only remaining function you can apply is `ML.RESIZE_IMAGE` (Step 6 shows it accepts either value type) — `ML.CONVERT_COLOR_SPACE` also accepts integers, but nothing can put you back in the float domain. Order your pipeline accordingly: decode → resize → color space → convert type, last.
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
## Step 5 — `ML.CONVERT_COLOR_SPACE`, and the two different lumas
|
|
355
|
+
|
|
356
|
+
Four targets: `GRAYSCALE`, `HSV`, `YIQ`, `YUV`. The interesting one is that two of them compute a luminance channel, and they do not agree.
|
|
357
|
+
|
|
358
|
+
```python
|
|
359
|
+
spaces = ['GRAYSCALE', 'HSV', 'YIQ', 'YUV']
|
|
360
|
+
select = ',\n '.join(
|
|
361
|
+
f"ML.CONVERT_COLOR_SPACE({img('swatch.png')}, '{s}').dimensions AS {s.lower()}_dims,\n "
|
|
362
|
+
f"ML.CONVERT_COLOR_SPACE({img('swatch.png')}, '{s}').values AS {s.lower()}"
|
|
363
|
+
for s in spaces)
|
|
364
|
+
query = f'SELECT\n {select}'
|
|
365
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
366
|
+
|
|
367
|
+
dims = {s: list(row[f'{s.lower()}_dims']) for s in spaces}
|
|
368
|
+
converted = {s: np.array(row[s.lower()]).reshape(dims[s]) for s in spaces}
|
|
369
|
+
for s in spaces:
|
|
370
|
+
print(f'{s:10s} dimensions={dims[s]}')
|
|
371
|
+
for i, pixel in enumerate(converted[s].reshape(-1, dims[s][-1])):
|
|
372
|
+
print(f'{"":12s}pixel {i} (RGB {swatch_a.reshape(-1, 3)[i].tolist()}): {pixel.tolist()}')
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
**`GRAYSCALE` changes the channel count — it returns 1, not 3.** That is the opposite of `ML.DECODE_IMAGE`, which in Step 2 replicated a single-channel grayscale PNG *up* to 3. So a decode-then-grayscale pipeline goes 1 → 3 → 1, and the "always 3 channels" rule from Step 2 is a rule about *decoding*, not about the family. `HSV`, `YIQ`, and `YUV` keep 3 channels and fill all three with genuinely distinct values.
|
|
376
|
+
|
|
377
|
+
`HSV`'s hue is on **`[0, 1]`, not degrees**: pixel 1's hue of ~0.0556 is 20°/360°, and pixel 2's ~0.583 is 210°/360°. A model or a threshold expecting degrees is off by a factor of 360.
|
|
378
|
+
|
|
379
|
+
Now the part worth stopping on. `GRAYSCALE`'s value and `YIQ`'s first channel are both luma, both computed from the same RGB, and they are different numbers. Which weights does each use?
|
|
380
|
+
|
|
381
|
+
```python
|
|
382
|
+
bt601 = np.array([0.299, 0.587, 0.114]) # the true ITU-R BT.601 luma coefficients
|
|
383
|
+
rounded = np.array([0.2989, 0.5870, 0.1140]) # the 4-decimal variant TensorFlow's rgb_to_grayscale uses
|
|
384
|
+
|
|
385
|
+
rgb = swatch_a.astype(np.float64).reshape(-1, 3) / 255.0
|
|
386
|
+
bq_grayscale = converted['GRAYSCALE'][..., 0].ravel()
|
|
387
|
+
bq_yiq_y = converted['YIQ'][..., 0].ravel()
|
|
388
|
+
|
|
389
|
+
rows = []
|
|
390
|
+
for label, actual in [('GRAYSCALE', bq_grayscale), ('YIQ channel Y', bq_yiq_y)]:
|
|
391
|
+
rows.append({
|
|
392
|
+
'BigQuery output': label,
|
|
393
|
+
'max diff vs [0.299, 0.587, 0.114]': np.abs(actual - rgb @ bt601).max(),
|
|
394
|
+
'max diff vs [0.2989, 0.5870, 0.1140]': np.abs(actual - rgb @ rounded).max(),
|
|
395
|
+
})
|
|
396
|
+
display(pd.DataFrame(rows))
|
|
397
|
+
|
|
398
|
+
gap = bq_grayscale - bq_yiq_y
|
|
399
|
+
print(f'GRAYSCALE - YIQ.Y per pixel: {gap.tolist()}')
|
|
400
|
+
print(f'as 8-bit levels (x255): {(gap * 255).tolist()}')
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
Two different lumas, each matching one weight vector to machine epsilon and neither matching the other:
|
|
404
|
+
|
|
405
|
+
- **`GRAYSCALE` uses `[0.2989, 0.5870, 0.1140]`** — the 4-decimal rounding that TensorFlow's `tf.image.rgb_to_grayscale` hardcodes.
|
|
406
|
+
- **`YIQ`'s Y uses `[0.299, 0.587, 0.114]`** — the actual BT.601 coefficients, exactly.
|
|
407
|
+
|
|
408
|
+
The gap is real but tiny — a fraction of one 8-bit level. It will never be visible and it will never change a classification. It matters for exactly one thing, which is worth knowing before it costs you an afternoon: **`GRAYSCALE` and `ML.CONVERT_COLOR_SPACE(..., 'YIQ')`'s Y are not interchangeable in a bit-for-bit reproducibility check.** If you are diffing a BigQuery preprocessing pipeline against a reimplementation elsewhere, you have to match the right one.
|
|
409
|
+
|
|
410
|
+
Integer-valued image data is accepted too, and is normalized on the way in rather than treated as already-scaled:
|
|
411
|
+
|
|
412
|
+
```python
|
|
413
|
+
query = f"""
|
|
414
|
+
SELECT ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'HSV').values AS from_float,
|
|
415
|
+
ML.CONVERT_COLOR_SPACE(ML.CONVERT_IMAGE_TYPE({img('swatch.png')}), 'HSV').values AS from_int
|
|
416
|
+
"""
|
|
417
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
418
|
+
print(f'from FLOAT64 input : {list(row["from_float"])}')
|
|
419
|
+
print(f'from INT64 input : {list(row["from_int"])}')
|
|
420
|
+
print(f'identical: {list(row["from_float"]) == list(row["from_int"])}')
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
Identical, and the output is `FLOAT64` either way. So `ML.CONVERT_COLOR_SPACE` divides integer input by 255 before converting — it never mistakes a `200` for a value already on `[0, 1]`. That is the safe behavior, and it means the pipeline order from Step 4 is a recommendation rather than a correctness requirement for this function.
|
|
424
|
+
|
|
425
|
+
An unrecognized target is rejected by name:
|
|
426
|
+
|
|
427
|
+
```python
|
|
428
|
+
try:
|
|
429
|
+
client.query(f"SELECT ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'LAB').values",
|
|
430
|
+
job_config=no_cache).result()
|
|
431
|
+
except BadRequest as e:
|
|
432
|
+
print(str(e).split(';')[0])
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
## Step 6 — `ML.RESIZE_IMAGE`: bilinear, float32, and type-preserving
|
|
438
|
+
|
|
439
|
+
The 4×8 gradient is the test image here — big enough to have interior pixels, small enough to print. Start with what `preserve_aspect_ratio` actually does to the output dimensions.
|
|
440
|
+
|
|
441
|
+
```python
|
|
442
|
+
targets = [(4, 4, True), (3, 3, True), (2, 2, True), (9, 9, True), (4, 4, False)]
|
|
443
|
+
select = ',\n '.join(
|
|
444
|
+
f'ML.RESIZE_IMAGE({img("gradient.png")}, {h}, {w}, {str(p).upper()}).dimensions AS t{i}'
|
|
445
|
+
for i, (h, w, p) in enumerate(targets))
|
|
446
|
+
row = list(client.query(f'SELECT\n {select}', job_config=no_cache).result())[0]
|
|
447
|
+
|
|
448
|
+
print(f'source dimensions: {list(gradient_a.shape)}\n')
|
|
449
|
+
out = []
|
|
450
|
+
for i, (h, w, p) in enumerate(targets):
|
|
451
|
+
dims = list(row[f't{i}'])
|
|
452
|
+
scale = min(h / gradient_a.shape[0], w / gradient_a.shape[1]) if p else None
|
|
453
|
+
out.append({'target (h, w)': f'{h} x {w}', 'preserve_aspect_ratio': p,
|
|
454
|
+
'implied scale': round(scale, 4) if scale else '—',
|
|
455
|
+
'unrounded h x w': f'{gradient_a.shape[0] * scale:g} x {gradient_a.shape[1] * scale:g}' if scale else '—',
|
|
456
|
+
'result dimensions': dims})
|
|
457
|
+
display(pd.DataFrame(out))
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
With `preserve_aspect_ratio = TRUE` the two target values are a **bounding box, not a size**: the scale is `min(target_h / h, target_w / w)` and the result is the largest image inside the box at the original aspect ratio. With `FALSE` you get exactly what you asked for, distortion included.
|
|
461
|
+
|
|
462
|
+
Look at the two rows where the scaled dimension lands on a half. `4 × 8` into a `3 × 3` box scales by 0.375, giving an unrounded height of 1.5, and the result is **2**. Into a `9 × 9` box it scales by 1.125, giving an unrounded height of 4.5, and the result is **4**. Half rounds up in one case and down in the other — that is round-half-to-even, the rounding NumPy and TensorFlow use and not the one SQL's `ROUND()` uses. Step 7 shows why that is exactly what you would expect.
|
|
463
|
+
|
|
464
|
+
Now the pixel values. A 4×8 down to 2×4 is a clean 2:1 in both directions:
|
|
465
|
+
|
|
466
|
+
```python
|
|
467
|
+
query = f'SELECT ML.RESIZE_IMAGE({img("gradient.png")}, 2, 4, FALSE).values AS v'
|
|
468
|
+
resized = np.array(list(client.query(query, job_config=no_cache).result())[0]['v']).reshape(2, 4, 3)
|
|
469
|
+
print('red channel of the resized 2x4 (x255):')
|
|
470
|
+
print(np.round(resized[..., 0] * 255, 6))
|
|
471
|
+
print('\nred channel of the 4x8 source (x255):')
|
|
472
|
+
print(gradient_a[..., 0])
|
|
473
|
+
print(f'\nsingle value, full precision: {resized[0, 0, 0]!r}')
|
|
474
|
+
print(f'nearest float32: {np.float32(resized[0, 0, 0]).item()!r}')
|
|
475
|
+
print(f'exactly representable in float32: {np.float64(np.float32(resized[0, 0, 0])) == resized[0, 0, 0]}')
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Two things.
|
|
479
|
+
|
|
480
|
+
**The interpolation is bilinear with half-pixel centers.** Output pixel `[0,0]` sits between source columns 0 and 1 (red values 0 and 32) and between source rows 0 and 1, and comes back at 16/255 — the average of the four neighbors, not a copy of the top-left pixel. That is `align_corners = False` sampling, the modern default.
|
|
481
|
+
|
|
482
|
+
**The values are float32, unlike everything else in this family.** Every number `ML.DECODE_IMAGE` and `ML.CONVERT_COLOR_SPACE` returned above was float64-exact; this one is a float64 that exactly equals its float32 neighbor, which is the signature of a value computed in single precision and widened on the way out. It costs about seven significant digits. Irrelevant for feeding a model — models are float32 anyway — and decisive if you are diffing against a float64 reimplementation, which is the trap Step 5's luma finding also sets.
|
|
483
|
+
|
|
484
|
+
Resize is the one function in the family that **preserves the value type** rather than forcing float:
|
|
485
|
+
|
|
486
|
+
```python
|
|
487
|
+
query = f"""
|
|
488
|
+
SELECT ML.RESIZE_IMAGE(ML.CONVERT_IMAGE_TYPE({img('swatch.png')}), 1, 1, FALSE).values AS int_in_int_out,
|
|
489
|
+
ML.RESIZE_IMAGE({img('swatch.png')}, 1, 1, FALSE).values AS float_in_float_out
|
|
490
|
+
"""
|
|
491
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
492
|
+
print(f'source pixels : {swatch_a.reshape(-1, 3).tolist()}')
|
|
493
|
+
print(f'exact channel means : {swatch_a.astype(np.float64).reshape(-1, 3).mean(axis=0).tolist()}')
|
|
494
|
+
print(f'INT64 in -> out : {list(row["int_in_int_out"])}')
|
|
495
|
+
print(f'FLOAT64 in -> out x255: {[v * 255 for v in row["float_in_float_out"]]}')
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
Integers in, integers out. The blue channel's true mean is 152.5 and it comes back as 152 — half-to-even again, consistent with the dimension rounding above. Feeding integers to resize therefore quantizes at every resize step; keep the pipeline in floats and convert last, as Step 4 concluded for a different reason.
|
|
499
|
+
|
|
500
|
+
### The failure mode worth knowing about
|
|
501
|
+
|
|
502
|
+
Ask for an aspect-preserving fit whose scale rounds a dimension down to zero — the 4×8 gradient into a 1×1 box scales by 0.125, giving a height of 0.5 — and the query fails.
|
|
503
|
+
|
|
504
|
+
> **The client library will retry this for minutes if you let it.** BigQuery reports it as a generic internal error with the standard "this is usually caused by a transient issue" advice, and `google-cloud-bigquery`'s default job-retry policy believes it: it resubmits the job, which fails identically, repeatedly. It is fully deterministic and no amount of retrying will change it. **`job_retry=None` is what makes this cell return in seconds instead of hanging.**
|
|
505
|
+
|
|
506
|
+
> **Catch the base class, and read the failure off the job.** The same deterministic failure has surfaced here as both `InternalServerError` (HTTP 500) and `BadRequest` (HTTP 400) on different runs, depending on which API call observes the dead job, and the 400 form arrives with a generic message that omits the diagnostic code. `job.error_result['message']` carries the full text either way, so catch `GoogleAPICallError` — the parent of both — and print the job's own error rather than the exception's.
|
|
507
|
+
|
|
508
|
+
```python
|
|
509
|
+
from google.api_core.exceptions import GoogleAPICallError
|
|
510
|
+
|
|
511
|
+
query = f'SELECT ML.RESIZE_IMAGE({img("gradient.png")}, 1, 1, TRUE).dimensions'
|
|
512
|
+
started = time.time()
|
|
513
|
+
job = client.query(query, job_config=no_cache, job_retry=None)
|
|
514
|
+
try:
|
|
515
|
+
job.result()
|
|
516
|
+
print('Unexpectedly succeeded')
|
|
517
|
+
except GoogleAPICallError as e:
|
|
518
|
+
print(f'Failed in {time.time() - started:.1f}s as {type(e).__name__} (HTTP {e.code}).\n')
|
|
519
|
+
detail = job.error_result
|
|
520
|
+
if not detail:
|
|
521
|
+
job.reload()
|
|
522
|
+
detail = job.error_result
|
|
523
|
+
print((detail or {}).get('message', str(e)))
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
The reproducible input rule is: **`preserve_aspect_ratio = TRUE` fails whenever `min(target_h / h, target_w / w)` scales either source dimension to less than 0.5**, i.e. whenever it rounds to zero. Verified on two differently-shaped sources; the `2 × 2` fit two cells up is the same target size on the same image with a non-degenerate result, so it is the rounding-to-zero and not the small target that does it.
|
|
527
|
+
|
|
528
|
+
What produces the internal error rather than a clean argument error is not observable from outside. A zero-sized dimension reaching an op that cannot accept one would explain it, and so would several other things; the message says nothing either way. What is worth carrying forward is operational, not diagnostic: **a "transient" internal error from these functions may be perfectly deterministic**, and the guard is to bound the target box so no dimension can round to zero — check `min(th/h, tw/w) * min(h, w) >= 0.5` before the query, or simply pass `FALSE` and accept the distortion.
|
|
529
|
+
|
|
530
|
+
|
|
531
|
+
---
|
|
532
|
+
## Step 7 — All four are TensorFlow image ops
|
|
533
|
+
|
|
534
|
+
Every finding above has the same shape: the behavior is not what BigQuery's documentation says, and it is exactly what TensorFlow does. Rather than infer that from a family resemblance, diff it directly — run the conversions in BigQuery, run the corresponding `tf.image` op locally, and subtract.
|
|
535
|
+
|
|
536
|
+
```python
|
|
537
|
+
import tensorflow as tf
|
|
538
|
+
|
|
539
|
+
query = f"""
|
|
540
|
+
SELECT
|
|
541
|
+
ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'GRAYSCALE').values AS grayscale,
|
|
542
|
+
ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'HSV').values AS hsv,
|
|
543
|
+
ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'YIQ').values AS yiq,
|
|
544
|
+
ML.CONVERT_COLOR_SPACE({img('swatch.png')}, 'YUV').values AS yuv,
|
|
545
|
+
ML.RESIZE_IMAGE({img('gradient.png')}, 2, 4, FALSE).values AS resize_even,
|
|
546
|
+
ML.RESIZE_IMAGE({img('gradient.png')}, 3, 5, FALSE).values AS resize_odd,
|
|
547
|
+
ML.CONVERT_IMAGE_TYPE({img('swatch.png')}).values AS to_uint8
|
|
548
|
+
"""
|
|
549
|
+
row = list(client.query(query, job_config=no_cache).result())[0]
|
|
550
|
+
|
|
551
|
+
swatch_f64 = swatch_a.astype(np.float64) / 255.0
|
|
552
|
+
grad_f64 = gradient_a.astype(np.float64) / 255.0
|
|
553
|
+
|
|
554
|
+
# Pin the tensor dtype explicitly. BigQuery computes the color-space conversions in
|
|
555
|
+
# double, so the reference has to as well -- and handing tf.image a bare NumPy float64
|
|
556
|
+
# array does not reliably get you there (the `reference dtype` column below is the check).
|
|
557
|
+
swatch_t64 = tf.constant(swatch_f64, tf.float64)
|
|
558
|
+
|
|
559
|
+
cases = [
|
|
560
|
+
('ML.CONVERT_COLOR_SPACE GRAYSCALE', row['grayscale'],
|
|
561
|
+
tf.image.rgb_to_grayscale(swatch_t64).numpy(),
|
|
562
|
+
'tf.image.rgb_to_grayscale, called as-is'),
|
|
563
|
+
('ML.CONVERT_COLOR_SPACE GRAYSCALE', row['grayscale'],
|
|
564
|
+
(swatch_f64 @ rounded)[..., None],
|
|
565
|
+
'the same weights, evaluated in float64'),
|
|
566
|
+
('ML.CONVERT_COLOR_SPACE HSV', row['hsv'],
|
|
567
|
+
tf.image.rgb_to_hsv(swatch_t64).numpy(), 'tf.image.rgb_to_hsv (float64)'),
|
|
568
|
+
('ML.CONVERT_COLOR_SPACE YIQ', row['yiq'],
|
|
569
|
+
tf.image.rgb_to_yiq(swatch_t64).numpy(), 'tf.image.rgb_to_yiq (float64)'),
|
|
570
|
+
('ML.CONVERT_COLOR_SPACE YUV', row['yuv'],
|
|
571
|
+
tf.image.rgb_to_yuv(swatch_t64).numpy(), 'tf.image.rgb_to_yuv (float64)'),
|
|
572
|
+
# Resize runs in float32 (Step 6), so cast the input to match.
|
|
573
|
+
('ML.RESIZE_IMAGE 4x8 -> 2x4', row['resize_even'],
|
|
574
|
+
tf.image.resize(tf.constant(grad_f64, tf.float32), [2, 4], method='bilinear').numpy(),
|
|
575
|
+
'tf.image.resize bilinear (float32)'),
|
|
576
|
+
('ML.RESIZE_IMAGE 4x8 -> 3x5', row['resize_odd'],
|
|
577
|
+
tf.image.resize(tf.constant(grad_f64, tf.float32), [3, 5], method='bilinear').numpy(),
|
|
578
|
+
'tf.image.resize bilinear (float32)'),
|
|
579
|
+
('ML.CONVERT_IMAGE_TYPE', row['to_uint8'],
|
|
580
|
+
tf.image.convert_image_dtype(swatch_t64, tf.uint8).numpy(),
|
|
581
|
+
'tf.image.convert_image_dtype -> uint8'),
|
|
582
|
+
]
|
|
583
|
+
|
|
584
|
+
EPS64, EPS32 = np.finfo(np.float64).eps, np.finfo(np.float32).eps
|
|
585
|
+
|
|
586
|
+
def compare(bq, ref):
|
|
587
|
+
"""Diff, plus the precision the gap is consistent with."""
|
|
588
|
+
bq, ref = np.array(bq, dtype=np.float64), ref.astype(np.float64).ravel()
|
|
589
|
+
diff, scale = float(np.abs(bq - ref).max()), float(np.abs(bq).max())
|
|
590
|
+
if diff == 0.0:
|
|
591
|
+
return diff, 'exact'
|
|
592
|
+
if diff <= 4 * EPS64 * scale:
|
|
593
|
+
return diff, 'double precision (<= a few ULP)'
|
|
594
|
+
if diff <= 4 * EPS32 * scale:
|
|
595
|
+
return diff, 'single precision (float32 somewhere in the op)'
|
|
596
|
+
return diff, 'a different answer'
|
|
597
|
+
|
|
598
|
+
table = []
|
|
599
|
+
for name, bq, ref, op in cases:
|
|
600
|
+
diff, verdict = compare(bq, ref)
|
|
601
|
+
table.append({'BigQuery function': name, 'TensorFlow op': op,
|
|
602
|
+
'reference dtype': str(ref.dtype), 'max |difference|': diff,
|
|
603
|
+
'consistent with': verdict})
|
|
604
|
+
display(pd.DataFrame(table))
|
|
605
|
+
|
|
606
|
+
single = [t['BigQuery function'] for t in table if t['consistent with'].startswith('single')]
|
|
607
|
+
print(f'TensorFlow {tf.__version__}')
|
|
608
|
+
print(f'single-precision rows: {", ".join(single) if single else "none"}')
|
|
609
|
+
|
|
610
|
+
# Which side is the single precision on? Compare BigQuery to BigQuery: the HSV values
|
|
611
|
+
# from this multi-function query against the ones Step 5 got with HSV alone.
|
|
612
|
+
delta = float(np.abs(np.array(row['hsv']) - np.array(converted['HSV']).ravel()).max())
|
|
613
|
+
print(f'BigQuery HSV here vs Step 5 (HSV alone in its query): max |difference| {delta:.6e}')
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
**`ML.CONVERT_COLOR_SPACE(..., 'HSV')` and both `ML.RESIZE_IMAGE` cases are bit-exact** — a difference of literally zero, including the 4×8 → 3×5 resize where the scale factor is not an integer ratio in either direction. `ML.CONVERT_IMAGE_TYPE` is exact too, since it produces integers.
|
|
617
|
+
|
|
618
|
+
`YIQ` and `YUV` land a last-place unit of a double away from `tf.image`'s answer — the residue of doing the same arithmetic in a different order, not a different formula.
|
|
619
|
+
|
|
620
|
+
`GRAYSCALE` is the row with a documented story. Called the ordinary way, `tf.image.rgb_to_grayscale` is eight orders of magnitude further off than `YIQ` is, and the reason is in TensorFlow's own source: it does `flt_image = convert_image_dtype(images, dtypes.float32)` before applying the weights, then converts back — so the returned tensor is still a double, but the arithmetic ran in **float32**. Apply the identical weights in float64 and the gap collapses to the same last-place residue as everything else. **BigQuery runs this in double where TensorFlow does not** — the algorithm is TensorFlow's (Step 5 pinned the weights to its 4-decimal constants), the precision is better than TensorFlow's.
|
|
621
|
+
|
|
622
|
+
That is also why the `consistent with` column is worth more than the raw magnitude: a ~1e-8 gap is not "a different formula," it is the resolution of a single-precision float, and it says only that *someone* on one side of the comparison spent a float32.
|
|
623
|
+
|
|
624
|
+
**The `reference dtype` column is there because this comparison is easy to get wrong, and the wrong version looks like a finding.** Hand `tf.image` a bare NumPy `float64` array rather than an explicitly typed tensor and the op can return **float32** — which turns the bit-exact `HSV` row into one the table classifies as single precision, at the same magnitude as the real `GRAYSCALE` result above it — an artifact of the measurement setup, indistinguishable from a property of the engine. That is why the cell pins its reference tensor with `tf.constant(..., tf.float64)` and prints the dtype it actually got. The last line of the cell is the control on the other side: BigQuery returns the **identical** `HSV` values whether the conversion sits alone in a query or beside six other image functions, so the precision of these functions is a property of the function, not of the query it lands in.
|
|
625
|
+
|
|
626
|
+
This is the practical takeaway of the whole notebook. When the reference page is silent or wrong — the channel count, the closed ranges, the rounding rule, the luma weights, the interpolation convention — **the answer is what `tf.image` does**, and `tf.image`'s documentation is specific where BigQuery's is not.
|
|
627
|
+
|
|
628
|
+
|
|
629
|
+
---
|
|
630
|
+
## Step 8 — The real path: an object table over Cloud Storage
|
|
631
|
+
|
|
632
|
+
Everything above used `BYTES` literals to keep the values reproducible. Production input is an [object table](https://cloud.google.com/bigquery/docs/object-tables): a read-only table over files in Cloud Storage whose `data` pseudocolumn is the file's bytes.
|
|
633
|
+
|
|
634
|
+
Unlike the functions themselves, an object table **does** need a Cloud Resource Connection, and the connection's service account needs read access to the bucket.
|
|
635
|
+
|
|
636
|
+
> **This changes IAM on your project** — it grants `roles/storage.objectViewer` to one newly-created, narrowly-scoped service account. The grant is checked explicitly rather than assumed: a silently-swallowed failure here surfaces as a confusing permission error on the query two cells later.
|
|
637
|
+
|
|
638
|
+
> **The bucket is never created or deleted by this notebook** — set `BUCKET` above to one you already own in the same location as `DATASET_ID`. Cleanup removes only the objects this notebook wrote, under the `bq_ml/image/` prefix.
|
|
639
|
+
|
|
640
|
+
```python
|
|
641
|
+
import json as _json
|
|
642
|
+
|
|
643
|
+
prefix = 'bq_ml/image/'
|
|
644
|
+
for name, data in raw.items():
|
|
645
|
+
blob = gcs_bucket.blob(prefix + name)
|
|
646
|
+
blob.upload_from_string(data, content_type='image/jpeg' if name.endswith('.jpg') else 'image/png')
|
|
647
|
+
print(f'Uploaded {len(raw)} objects to gs://{BUCKET}/{prefix}')
|
|
648
|
+
|
|
649
|
+
r_conn = subprocess.run(
|
|
650
|
+
['bq', 'mk', '--connection', '--location', LOCATION, '--connection_type', 'CLOUD_RESOURCE',
|
|
651
|
+
'--project_id', PROJECT_ID, CONNECTION_ID],
|
|
652
|
+
capture_output=True, text=True,
|
|
653
|
+
)
|
|
654
|
+
if r_conn.returncode != 0 and 'already exists' not in r_conn.stderr.lower():
|
|
655
|
+
raise RuntimeError(f'Failed to create connection {CONNECTION_ID}:\n{r_conn.stderr}')
|
|
656
|
+
|
|
657
|
+
r_show = subprocess.run(
|
|
658
|
+
['bq', 'show', '--connection', '--format=json', '--project_id', PROJECT_ID, '--location', LOCATION, CONNECTION_ID],
|
|
659
|
+
capture_output=True, text=True, check=True,
|
|
660
|
+
)
|
|
661
|
+
connection_sa = _json.loads(r_show.stdout)['cloudResource']['serviceAccountId']
|
|
662
|
+
print('Connection service account:', connection_sa)
|
|
663
|
+
|
|
664
|
+
r_iam = subprocess.run(
|
|
665
|
+
['gcloud', 'projects', 'add-iam-policy-binding', PROJECT_ID,
|
|
666
|
+
f'--member=serviceAccount:{connection_sa}', '--role=roles/storage.objectViewer', '--quiet'],
|
|
667
|
+
capture_output=True, text=True,
|
|
668
|
+
)
|
|
669
|
+
if r_iam.returncode != 0:
|
|
670
|
+
raise RuntimeError(f'Failed to grant roles/storage.objectViewer to {connection_sa}:\n{r_iam.stderr}')
|
|
671
|
+
print('Granted roles/storage.objectViewer')
|
|
672
|
+
|
|
673
|
+
time.sleep(60) # initial wait -- the query below retries further, since propagation is variable
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
```python
|
|
677
|
+
query = f"""
|
|
678
|
+
CREATE OR REPLACE EXTERNAL TABLE `{PROJECT_ID}.{DATASET_ID}.image_object_table`
|
|
679
|
+
WITH CONNECTION `{PROJECT_ID}.{LOCATION}.{CONNECTION_ID}`
|
|
680
|
+
OPTIONS (
|
|
681
|
+
object_metadata = 'SIMPLE',
|
|
682
|
+
uris = ['gs://{BUCKET}/{prefix}*']
|
|
683
|
+
)
|
|
684
|
+
"""
|
|
685
|
+
client.query(query).result()
|
|
686
|
+
|
|
687
|
+
# IAM propagation is genuinely variable -- retry on a permission error rather
|
|
688
|
+
# than gambling on the fixed wait above.
|
|
689
|
+
from google.api_core.exceptions import Forbidden
|
|
690
|
+
|
|
691
|
+
listing = f"""
|
|
692
|
+
SELECT REGEXP_EXTRACT(uri, r'[^/]+$') AS file, content_type, size, updated
|
|
693
|
+
FROM `{PROJECT_ID}.{DATASET_ID}.image_object_table`
|
|
694
|
+
ORDER BY file
|
|
695
|
+
"""
|
|
696
|
+
for attempt in range(1, 9):
|
|
697
|
+
try:
|
|
698
|
+
display(client.query(listing, job_config=no_cache).to_dataframe())
|
|
699
|
+
break
|
|
700
|
+
except (BadRequest, Forbidden) as e:
|
|
701
|
+
if 'permission' not in str(e).lower() or attempt == 8:
|
|
702
|
+
raise
|
|
703
|
+
print(f'Attempt {attempt}/8: permission not yet propagated, waiting 20s...')
|
|
704
|
+
time.sleep(20)
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
An object table exposes metadata columns (`uri`, `content_type`, `size`, `updated`) plus the `data` pseudocolumn holding the bytes. `data` is what `ML.DECODE_IMAGE` consumes.
|
|
708
|
+
|
|
709
|
+
Note that `content_type` is what Cloud Storage was told at upload time, not what the file is. It is metadata, not validation — filter on it if you like, but Step 2's decode error is the only thing that actually checks.
|
|
710
|
+
|
|
711
|
+
Now the whole pipeline in one statement: bytes → decode → fixed-size resize → grayscale → integers, written to a table rather than returned to the editor.
|
|
712
|
+
|
|
713
|
+
```python
|
|
714
|
+
query = f"""
|
|
715
|
+
CREATE OR REPLACE TABLE `{PROJECT_ID}.{DATASET_ID}.image_features` AS
|
|
716
|
+
SELECT
|
|
717
|
+
REGEXP_EXTRACT(uri, r'[^/]+$') AS file,
|
|
718
|
+
ML.CONVERT_IMAGE_TYPE(
|
|
719
|
+
ML.CONVERT_COLOR_SPACE(
|
|
720
|
+
ML.RESIZE_IMAGE(ML.DECODE_IMAGE(data), 4, 4, FALSE),
|
|
721
|
+
'GRAYSCALE')) AS features
|
|
722
|
+
FROM `{PROJECT_ID}.{DATASET_ID}.image_object_table`
|
|
723
|
+
WHERE content_type IN ('image/png', 'image/jpeg')
|
|
724
|
+
"""
|
|
725
|
+
client.query(query).result()
|
|
726
|
+
|
|
727
|
+
summary = f"""
|
|
728
|
+
SELECT file,
|
|
729
|
+
features.dimensions AS dimensions,
|
|
730
|
+
ARRAY_LENGTH(features.values) AS n_values,
|
|
731
|
+
features.values[OFFSET(0)] AS first_value
|
|
732
|
+
FROM `{PROJECT_ID}.{DATASET_ID}.image_features`
|
|
733
|
+
ORDER BY file
|
|
734
|
+
"""
|
|
735
|
+
display(client.query(summary, job_config=no_cache).to_dataframe())
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
Six source images of four different shapes and two formats, all reduced to the same dimensions and the same value count — a uniform feature vector a vision model can take as a batch. That uniformity is the entire point of the family, and it comes from two of the rules above: a `FALSE` aspect ratio pins height and width to exactly what was asked for, and the channel count is fixed by the last function in the chain (`GRAYSCALE` here, so 1 channel, per Step 5) rather than by the source images, which arrived with 1, 3, and 4 channels between them.
|
|
739
|
+
|
|
740
|
+
> **Write to a table, don't select the struct.** The reference pages warn that referencing these functions directly can fail to display in the BigQuery editor. That is a display limit, not a data limit — these images are tiny, but a 4000×3000 photo decodes to 36 million doubles, and the resize belongs *inside* the same statement that reads `data` so the large intermediate never materializes as a result.
|
|
741
|
+
|
|
742
|
+
The two remaining size limits are worth stating together, because one behaves differently than its wording suggests: **object-table image files must be under 20 MB and the `data` value passed to `ML.DECODE_IMAGE` must be at most 10 MB** — those are hard. The decoded `STRUCT`'s 60 MB ceiling is not: an image whose decoded struct would exceed it is **automatically downscaled, preserving aspect ratio**, rather than rejected. A silently resized input is a much subtler problem than a failed query, because the model still gets a valid tensor. If your pipeline handles large images, pin the size with an explicit `ML.RESIZE_IMAGE` instead of letting the ceiling do it for you.
|
|
743
|
+
|
|
744
|
+
### Where this goes next
|
|
745
|
+
|
|
746
|
+
These features feed a model that BigQuery did not train. `CREATE MODEL ... OPTIONS(model_type = 'TENSORFLOW', model_path = 'gs://...')` imports a vision SavedModel, and `ML.PREDICT` scores the table above — see `models/imported` (`models/imported/`) for the import mechanics end to end (its examples are tabular, but the `CREATE MODEL` shape is identical). Put the four functions in a `TRANSFORM` clause instead and the preprocessing is stored with the model and re-applied automatically at prediction time, which removes the possibility of training/serving skew in this stage of the pipeline entirely.
|
|
747
|
+
|
|
748
|
+
|
|
749
|
+
---
|
|
750
|
+
## Examples — `%%bigquery` Magics
|
|
751
|
+
|
|
752
|
+
The same pipeline using IPython magic commands — write SQL directly in cells without Python string wrapping.
|
|
753
|
+
|
|
754
|
+
```sql
|
|
755
|
+
%%bigquery --project {PROJECT_ID}
|
|
756
|
+
|
|
757
|
+
SELECT
|
|
758
|
+
REGEXP_EXTRACT(uri, r'[^/]+$') AS file,
|
|
759
|
+
ML.DECODE_IMAGE(data).dimensions AS source_dimensions,
|
|
760
|
+
ML.RESIZE_IMAGE(ML.DECODE_IMAGE(data), 4, 4, FALSE).dimensions AS resized_dimensions,
|
|
761
|
+
ML.CONVERT_IMAGE_TYPE(ML.DECODE_IMAGE(data)).values[OFFSET(0)] AS first_pixel_red
|
|
762
|
+
FROM `statmike-mlops-349915.bq_ml.image_object_table`
|
|
763
|
+
ORDER BY file
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
|
|
767
|
+
---
|
|
768
|
+
## Examples — BigFrames
|
|
769
|
+
|
|
770
|
+
There is **no** `bigframes.ml` wrapper for any of the four. BigFrames has a multimodal `blob` accessor (`Series.blob.image_resize()`, `.image_normalize()`) that reads and writes image *files* through Cloud Storage — a different mechanism producing files, not the numeric `STRUCT` these functions produce. To reach the BigQuery functions themselves, run the SQL through `read_gbq`.
|
|
771
|
+
|
|
772
|
+
The struct comes back as a Python `dict`, so `dimensions` and `values` are ordinary keys.
|
|
773
|
+
|
|
774
|
+
```python
|
|
775
|
+
import bigframes.pandas as bpd
|
|
776
|
+
|
|
777
|
+
bpd.close_session() # Reset session to apply project/location settings
|
|
778
|
+
bpd.options.bigquery.project = PROJECT_ID
|
|
779
|
+
bpd.options.bigquery.location = LOCATION
|
|
780
|
+
|
|
781
|
+
bdf = bpd.read_gbq(f"""
|
|
782
|
+
SELECT REGEXP_EXTRACT(uri, r'[^/]+$') AS file,
|
|
783
|
+
ML.RESIZE_IMAGE(ML.DECODE_IMAGE(data), 2, 2, FALSE) AS image
|
|
784
|
+
FROM `{PROJECT_ID}.{DATASET_ID}.image_object_table`
|
|
785
|
+
ORDER BY file
|
|
786
|
+
""")
|
|
787
|
+
pdf = bdf.to_pandas()
|
|
788
|
+
print(type(pdf['image'].iloc[0]))
|
|
789
|
+
print('dimensions:', pdf['image'].iloc[0]['dimensions'])
|
|
790
|
+
bdf
|
|
791
|
+
```
|