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.
Files changed (286) hide show
  1. bigquery_data_science/__init__.py +58 -0
  2. bigquery_data_science/_skills/PLANS.md +76 -0
  3. bigquery_data_science/_skills/bigquery-ai/SKILL.md +66 -0
  4. bigquery_data_science/_skills/bigquery-ai/narrative/ai_agg.md +528 -0
  5. bigquery_data_science/_skills/bigquery-ai/narrative/ai_classify.md +450 -0
  6. bigquery_data_science/_skills/bigquery-ai/narrative/ai_count_tokens.md +180 -0
  7. bigquery_data_science/_skills/bigquery-ai/narrative/ai_detect_anomalies.md +322 -0
  8. bigquery_data_science/_skills/bigquery-ai/narrative/ai_embed.md +425 -0
  9. bigquery_data_science/_skills/bigquery-ai/narrative/ai_evaluate.md +368 -0
  10. bigquery_data_science/_skills/bigquery-ai/narrative/ai_forecast.md +437 -0
  11. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate.md +693 -0
  12. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_bool.md +248 -0
  13. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_double.md +254 -0
  14. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_embedding.md +402 -0
  15. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_int.md +252 -0
  16. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_table.md +447 -0
  17. bigquery_data_science/_skills/bigquery-ai/narrative/ai_generate_text.md +356 -0
  18. bigquery_data_science/_skills/bigquery-ai/narrative/ai_if.md +373 -0
  19. bigquery_data_science/_skills/bigquery-ai/narrative/ai_key_drivers.md +331 -0
  20. bigquery_data_science/_skills/bigquery-ai/narrative/ai_parse_document.md +416 -0
  21. bigquery_data_science/_skills/bigquery-ai/narrative/ai_predict.md +559 -0
  22. bigquery_data_science/_skills/bigquery-ai/narrative/ai_score.md +310 -0
  23. bigquery_data_science/_skills/bigquery-ai/narrative/ai_search.md +465 -0
  24. bigquery_data_science/_skills/bigquery-ai/narrative/ai_similarity.md +371 -0
  25. bigquery_data_science/_skills/bigquery-ai/narrative/catalog_search.md +951 -0
  26. bigquery_data_science/_skills/bigquery-ai/narrative/content_analysis.md +284 -0
  27. bigquery_data_science/_skills/bigquery-ai/narrative/content_moderation.md +369 -0
  28. bigquery_data_science/_skills/bigquery-ai/narrative/data_enrichment.md +426 -0
  29. bigquery_data_science/_skills/bigquery-ai/narrative/document_intelligence.md +470 -0
  30. bigquery_data_science/_skills/bigquery-ai/narrative/document_rag.md +453 -0
  31. bigquery_data_science/_skills/bigquery-ai/narrative/image_deduplication.md +770 -0
  32. bigquery_data_science/_skills/bigquery-ai/narrative/log_analysis.md +668 -0
  33. bigquery_data_science/_skills/bigquery-ai/narrative/metric_diagnostics.md +568 -0
  34. bigquery_data_science/_skills/bigquery-ai/narrative/ml_annotate_image.md +680 -0
  35. bigquery_data_science/_skills/bigquery-ai/narrative/ml_generate_embedding.md +217 -0
  36. bigquery_data_science/_skills/bigquery-ai/narrative/ml_generate_text.md +223 -0
  37. bigquery_data_science/_skills/bigquery-ai/narrative/ml_process_document.md +392 -0
  38. bigquery_data_science/_skills/bigquery-ai/narrative/ml_transcribe.md +815 -0
  39. bigquery_data_science/_skills/bigquery-ai/narrative/ml_translate.md +600 -0
  40. bigquery_data_science/_skills/bigquery-ai/narrative/ml_understand_text.md +673 -0
  41. bigquery_data_science/_skills/bigquery-ai/narrative/multimodal_analysis.md +266 -0
  42. bigquery_data_science/_skills/bigquery-ai/narrative/rag_pipeline.md +593 -0
  43. bigquery_data_science/_skills/bigquery-ai/narrative/semantic_search.md +510 -0
  44. bigquery_data_science/_skills/bigquery-ai/narrative/tabular_prediction.md +485 -0
  45. bigquery_data_science/_skills/bigquery-ai/narrative/time_series_intelligence.md +489 -0
  46. bigquery_data_science/_skills/bigquery-ai/narrative/vector_search.md +672 -0
  47. bigquery_data_science/_skills/bigquery-ai/reference/augmented-analytics.md +77 -0
  48. bigquery_data_science/_skills/bigquery-ai/reference/cloud-ai-service-models.md +88 -0
  49. bigquery_data_science/_skills/bigquery-ai/reference/document-processing.md +95 -0
  50. bigquery_data_science/_skills/bigquery-ai/reference/embeddings-and-search.md +166 -0
  51. bigquery_data_science/_skills/bigquery-ai/reference/general-purpose-generation.md +87 -0
  52. bigquery_data_science/_skills/bigquery-ai/reference/managed-functions.md +72 -0
  53. bigquery_data_science/_skills/bigquery-ai/reference/predictive-ai.md +113 -0
  54. bigquery_data_science/_skills/bigquery-ai/reference/workflows.md +56 -0
  55. bigquery_data_science/_skills/bigquery-ai/skill.manifest.json +109 -0
  56. bigquery_data_science/_skills/bigquery-ai/syntax/INDEX.md +71 -0
  57. bigquery_data_science/_skills/bigquery-ai/syntax/aiagg.md +67 -0
  58. bigquery_data_science/_skills/bigquery-ai/syntax/aicausal_effect-covered-in-bigquery-ml.md +17 -0
  59. bigquery_data_science/_skills/bigquery-ai/syntax/aiclassify.md +72 -0
  60. bigquery_data_science/_skills/bigquery-ai/syntax/aicount_tokens.md +53 -0
  61. bigquery_data_science/_skills/bigquery-ai/syntax/aidetect_anomalies.md +63 -0
  62. bigquery_data_science/_skills/bigquery-ai/syntax/aiembed.md +85 -0
  63. bigquery_data_science/_skills/bigquery-ai/syntax/aievaluate.md +114 -0
  64. bigquery_data_science/_skills/bigquery-ai/syntax/aiforecast.md +123 -0
  65. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate.md +69 -0
  66. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_bool.md +53 -0
  67. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_double.md +45 -0
  68. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_embedding.md +108 -0
  69. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_int.md +45 -0
  70. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_table.md +64 -0
  71. bigquery_data_science/_skills/bigquery-ai/syntax/aigenerate_text.md +167 -0
  72. bigquery_data_science/_skills/bigquery-ai/syntax/aiif.md +56 -0
  73. bigquery_data_science/_skills/bigquery-ai/syntax/aikey_drivers.md +76 -0
  74. bigquery_data_science/_skills/bigquery-ai/syntax/aiparse_document.md +91 -0
  75. bigquery_data_science/_skills/bigquery-ai/syntax/aipredict.md +74 -0
  76. bigquery_data_science/_skills/bigquery-ai/syntax/aiscore.md +52 -0
  77. bigquery_data_science/_skills/bigquery-ai/syntax/aisearch.md +66 -0
  78. bigquery_data_science/_skills/bigquery-ai/syntax/aisimilarity.md +79 -0
  79. bigquery_data_science/_skills/bigquery-ai/syntax/choosing-between-these-and-the-ai-functions.md +11 -0
  80. bigquery_data_science/_skills/bigquery-ai/syntax/hybrid-search-capability.md +165 -0
  81. bigquery_data_science/_skills/bigquery-ai/syntax/mlannotate_image.md +24 -0
  82. bigquery_data_science/_skills/bigquery-ai/syntax/mlgenerate_embedding.md +34 -0
  83. bigquery_data_science/_skills/bigquery-ai/syntax/mlgenerate_text.md +65 -0
  84. bigquery_data_science/_skills/bigquery-ai/syntax/mlprocess_document.md +125 -0
  85. bigquery_data_science/_skills/bigquery-ai/syntax/mltranscribe.md +26 -0
  86. bigquery_data_science/_skills/bigquery-ai/syntax/mltranslate.md +27 -0
  87. bigquery_data_science/_skills/bigquery-ai/syntax/mlunderstand_text.md +32 -0
  88. bigquery_data_science/_skills/bigquery-ai/syntax/multimodal-input-patterns-by-function.md +128 -0
  89. bigquery_data_science/_skills/bigquery-ai/syntax/object-tables.md +109 -0
  90. bigquery_data_science/_skills/bigquery-ai/syntax/objectref-and-objectrefruntime-schema-reference.md +50 -0
  91. bigquery_data_science/_skills/bigquery-ai/syntax/objfetch_metadata.md +49 -0
  92. bigquery_data_science/_skills/bigquery-ai/syntax/objget_access_url.md +66 -0
  93. bigquery_data_science/_skills/bigquery-ai/syntax/objget_read_url.md +40 -0
  94. bigquery_data_science/_skills/bigquery-ai/syntax/objlist.md +34 -0
  95. bigquery_data_science/_skills/bigquery-ai/syntax/objmake_ref.md +58 -0
  96. bigquery_data_science/_skills/bigquery-ai/syntax/per-row-failures-and-the-retry-pattern.md +19 -0
  97. bigquery_data_science/_skills/bigquery-ai/syntax/setup-apis-connection-roles.md +39 -0
  98. bigquery_data_science/_skills/bigquery-ai/syntax/two-input-shapes.md +22 -0
  99. bigquery_data_science/_skills/bigquery-ai/syntax/vector_search.md +78 -0
  100. bigquery_data_science/_skills/bigquery-ai/syntax/what-the-five-have-in-common.md +27 -0
  101. bigquery_data_science/_skills/bigquery-data-science/SKILL.md +69 -0
  102. bigquery_data_science/_skills/bigquery-data-science/reference/namespace-matrix.md +112 -0
  103. bigquery_data_science/_skills/bigquery-data-science/skill.manifest.json +13 -0
  104. bigquery_data_science/_skills/bigquery-ml/SKILL.md +70 -0
  105. bigquery_data_science/_skills/bigquery-ml/narrative/airflow_with_kfp.md +379 -0
  106. bigquery_data_science/_skills/bigquery-ml/narrative/anomaly_fraud_detection.md +195 -0
  107. bigquery_data_science/_skills/bigquery-ml/narrative/arima_plus.md +635 -0
  108. bigquery_data_science/_skills/bigquery-ml/narrative/arima_plus_xreg.md +453 -0
  109. bigquery_data_science/_skills/bigquery-ml/narrative/autoencoder.md +470 -0
  110. bigquery_data_science/_skills/bigquery-ml/narrative/automl_classifier.md +291 -0
  111. bigquery_data_science/_skills/bigquery-ml/narrative/automl_regressor.md +274 -0
  112. bigquery_data_science/_skills/bigquery-ml/narrative/boosted_tree_classifier.md +449 -0
  113. bigquery_data_science/_skills/bigquery-ml/narrative/boosted_tree_regressor.md +400 -0
  114. bigquery_data_science/_skills/bigquery-ml/narrative/bucketizing.md +201 -0
  115. bigquery_data_science/_skills/bigquery-ml/narrative/causal_effect.md +773 -0
  116. bigquery_data_science/_skills/bigquery-ml/narrative/churn_retention.md +271 -0
  117. bigquery_data_science/_skills/bigquery-ml/narrative/cloud_workflows.md +370 -0
  118. bigquery_data_science/_skills/bigquery-ml/narrative/composer_airflow.md +475 -0
  119. bigquery_data_science/_skills/bigquery-ml/narrative/contribution_analysis.md +346 -0
  120. bigquery_data_science/_skills/bigquery-ml/narrative/cross_validation.md +185 -0
  121. bigquery_data_science/_skills/bigquery-ml/narrative/customer_segmentation.md +233 -0
  122. bigquery_data_science/_skills/bigquery-ml/narrative/dataform.md +372 -0
  123. bigquery_data_science/_skills/bigquery-ml/narrative/dbt.md +283 -0
  124. bigquery_data_science/_skills/bigquery-ml/narrative/difference_in_differences.md +280 -0
  125. bigquery_data_science/_skills/bigquery-ml/narrative/distance.md +195 -0
  126. bigquery_data_science/_skills/bigquery-ml/narrative/dnn_classifier.md +326 -0
  127. bigquery_data_science/_skills/bigquery-ml/narrative/dnn_regressor.md +308 -0
  128. bigquery_data_science/_skills/bigquery-ml/narrative/embeddings_classification.md +426 -0
  129. bigquery_data_science/_skills/bigquery-ml/narrative/encoding.md +238 -0
  130. bigquery_data_science/_skills/bigquery-ml/narrative/ensembling.md +278 -0
  131. bigquery_data_science/_skills/bigquery-ml/narrative/evaluation.md +445 -0
  132. bigquery_data_science/_skills/bigquery-ml/narrative/exploration.md +779 -0
  133. bigquery_data_science/_skills/bigquery-ml/narrative/export.md +321 -0
  134. bigquery_data_science/_skills/bigquery-ml/narrative/feature_engineering.md +280 -0
  135. bigquery_data_science/_skills/bigquery-ml/narrative/feature_store.md +652 -0
  136. bigquery_data_science/_skills/bigquery-ml/narrative/feature_store_workflow.md +426 -0
  137. bigquery_data_science/_skills/bigquery-ml/narrative/ga4_churn_prediction.md +285 -0
  138. bigquery_data_science/_skills/bigquery-ml/narrative/hierarchical_forecasting.md +441 -0
  139. bigquery_data_science/_skills/bigquery-ml/narrative/image.md +791 -0
  140. bigquery_data_science/_skills/bigquery-ml/narrative/imported.md +426 -0
  141. bigquery_data_science/_skills/bigquery-ml/narrative/kmeans.md +348 -0
  142. bigquery_data_science/_skills/bigquery-ml/narrative/linear_regression.md +372 -0
  143. bigquery_data_science/_skills/bigquery-ml/narrative/logistic_regression.md +390 -0
  144. bigquery_data_science/_skills/bigquery-ml/narrative/matrix_factorization.md +404 -0
  145. bigquery_data_science/_skills/bigquery-ml/narrative/model_monitoring.md +609 -0
  146. bigquery_data_science/_skills/bigquery-ml/narrative/pca.md +357 -0
  147. bigquery_data_science/_skills/bigquery-ml/narrative/price_elasticity_dml.md +286 -0
  148. bigquery_data_science/_skills/bigquery-ml/narrative/propensity_score_matching.md +350 -0
  149. bigquery_data_science/_skills/bigquery-ml/narrative/random_forest_classifier.md +445 -0
  150. bigquery_data_science/_skills/bigquery-ml/narrative/random_forest_regressor.md +409 -0
  151. bigquery_data_science/_skills/bigquery-ml/narrative/recommendation.md +281 -0
  152. bigquery_data_science/_skills/bigquery-ml/narrative/regression_based_forecasting.md +491 -0
  153. bigquery_data_science/_skills/bigquery-ml/narrative/remote.md +428 -0
  154. bigquery_data_science/_skills/bigquery-ml/narrative/scalers.md +325 -0
  155. bigquery_data_science/_skills/bigquery-ml/narrative/scheduled_queries.md +284 -0
  156. bigquery_data_science/_skills/bigquery-ml/narrative/sql_scripting.md +243 -0
  157. bigquery_data_science/_skills/bigquery-ml/narrative/survival_analysis.md +363 -0
  158. bigquery_data_science/_skills/bigquery-ml/narrative/synthetic_control.md +221 -0
  159. bigquery_data_science/_skills/bigquery-ml/narrative/text.md +215 -0
  160. bigquery_data_science/_skills/bigquery-ml/narrative/time_series.md +669 -0
  161. bigquery_data_science/_skills/bigquery-ml/narrative/transform_only.md +273 -0
  162. bigquery_data_science/_skills/bigquery-ml/narrative/uplift_cate.md +241 -0
  163. bigquery_data_science/_skills/bigquery-ml/narrative/vertex_kfp.md +360 -0
  164. bigquery_data_science/_skills/bigquery-ml/narrative/wide_and_deep_classifier.md +316 -0
  165. bigquery_data_science/_skills/bigquery-ml/narrative/wide_and_deep_regressor.md +298 -0
  166. bigquery_data_science/_skills/bigquery-ml/reference/classification.md +80 -0
  167. bigquery_data_science/_skills/bigquery-ml/reference/model-management.md +90 -0
  168. bigquery_data_science/_skills/bigquery-ml/reference/preprocessing-functions.md +234 -0
  169. bigquery_data_science/_skills/bigquery-ml/reference/regression.md +79 -0
  170. bigquery_data_science/_skills/bigquery-ml/reference/unsupervised-and-specialized.md +101 -0
  171. bigquery_data_science/_skills/bigquery-ml/reference/workflows-and-pipelines.md +111 -0
  172. bigquery_data_science/_skills/bigquery-ml/skill.manifest.json +177 -0
  173. bigquery_data_science/_skills/bigquery-ml/syntax/1-model_type-catalog.md +28 -0
  174. bigquery_data_science/_skills/bigquery-ml/syntax/2-task-mlevaluate-metric-columns.md +26 -0
  175. bigquery_data_science/_skills/bigquery-ml/syntax/3-capability-matrix-per-model-type.md +21 -0
  176. bigquery_data_science/_skills/bigquery-ml/syntax/4-explainability-weights-functions.md +14 -0
  177. bigquery_data_science/_skills/bigquery-ml/syntax/5-connection-matrix.md +11 -0
  178. bigquery_data_science/_skills/bigquery-ml/syntax/6-which-model-free-function-no-create-model-no-connection.md +15 -0
  179. bigquery_data_science/_skills/bigquery-ml/syntax/7-point-in-time-feature-retrieval-which-of-the-two.md +11 -0
  180. bigquery_data_science/_skills/bigquery-ml/syntax/INDEX.md +111 -0
  181. bigquery_data_science/_skills/bigquery-ml/syntax/aicausal_effect.md +85 -0
  182. bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus-forecasting-lifecycle-functions.md +14 -0
  183. bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus-univariate-time-series-forecasting.md +132 -0
  184. bigquery_data_science/_skills/bigquery-ml/syntax/arima_plus_xreg-multivariate-time-series-with-external-regressors.md +103 -0
  185. bigquery_data_science/_skills/bigquery-ml/syntax/autoencoder.md +102 -0
  186. bigquery_data_science/_skills/bigquery-ml/syntax/automl_classifier-automl_regressor.md +88 -0
  187. bigquery_data_science/_skills/bigquery-ml/syntax/boosted_tree_classifier-boosted_tree_regressor.md +117 -0
  188. bigquery_data_science/_skills/bigquery-ml/syntax/contribution_analysis.md +113 -0
  189. bigquery_data_science/_skills/bigquery-ml/syntax/dnn_classifier-dnn_regressor.md +107 -0
  190. bigquery_data_science/_skills/bigquery-ml/syntax/dnn_linear_combined_classifier-dnn_linear_combined_regressor-wide-and-deep.md +98 -0
  191. bigquery_data_science/_skills/bigquery-ml/syntax/explainability-functions-mlexplain_predict-mlglobal_explain-mlfeature_importance.md +7 -0
  192. bigquery_data_science/_skills/bigquery-ml/syntax/exploratory-data-analysis-mldescribe_data-mlcorrelation.md +11 -0
  193. bigquery_data_science/_skills/bigquery-ml/syntax/export-model.md +92 -0
  194. bigquery_data_science/_skills/bigquery-ml/syntax/feature-engineering-standalone-preprocessing-functions.md +13 -0
  195. bigquery_data_science/_skills/bigquery-ml/syntax/image-preprocessing-functions-mldecode_image-mlresize_image-mlconvert_image_type-mlconvert_color_space.md +63 -0
  196. bigquery_data_science/_skills/bigquery-ml/syntax/imported-models-tensorflow-tensorflow_lite-onnx-xgboost.md +36 -0
  197. bigquery_data_science/_skills/bigquery-ml/syntax/kmeans.md +87 -0
  198. bigquery_data_science/_skills/bigquery-ml/syntax/linear_reg-logistic_reg-generalized-linear-models.md +101 -0
  199. bigquery_data_science/_skills/bigquery-ml/syntax/matrix_factorization.md +162 -0
  200. bigquery_data_science/_skills/bigquery-ml/syntax/mladvanced_weights.md +76 -0
  201. bigquery_data_science/_skills/bigquery-ml/syntax/mlarima_coefficients.md +30 -0
  202. bigquery_data_science/_skills/bigquery-ml/syntax/mlarima_evaluate.md +49 -0
  203. bigquery_data_science/_skills/bigquery-ml/syntax/mlbag_of_words.md +47 -0
  204. bigquery_data_science/_skills/bigquery-ml/syntax/mlbucketize.md +47 -0
  205. bigquery_data_science/_skills/bigquery-ml/syntax/mlcentroids.md +46 -0
  206. bigquery_data_science/_skills/bigquery-ml/syntax/mlconfusion_matrix.md +56 -0
  207. bigquery_data_science/_skills/bigquery-ml/syntax/mlconvert_color_space.md +53 -0
  208. bigquery_data_science/_skills/bigquery-ml/syntax/mlconvert_image_type.md +39 -0
  209. bigquery_data_science/_skills/bigquery-ml/syntax/mlcorrelation.md +78 -0
  210. bigquery_data_science/_skills/bigquery-ml/syntax/mldecode_image.md +44 -0
  211. bigquery_data_science/_skills/bigquery-ml/syntax/mldescribe_data.md +74 -0
  212. bigquery_data_science/_skills/bigquery-ml/syntax/mldetect_anomalies.md +86 -0
  213. bigquery_data_science/_skills/bigquery-ml/syntax/mldistance.md +48 -0
  214. bigquery_data_science/_skills/bigquery-ml/syntax/mlentity_features_at_time.md +56 -0
  215. bigquery_data_science/_skills/bigquery-ml/syntax/mlevaluate.md +72 -0
  216. bigquery_data_science/_skills/bigquery-ml/syntax/mlexplain_forecast.md +50 -0
  217. bigquery_data_science/_skills/bigquery-ml/syntax/mlexplain_predict.md +66 -0
  218. bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_cross.md +46 -0
  219. bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_importance.md +47 -0
  220. bigquery_data_science/_skills/bigquery-ml/syntax/mlfeature_info.md +50 -0
  221. bigquery_data_science/_skills/bigquery-ml/syntax/mlfeatures_at_time.md +51 -0
  222. bigquery_data_science/_skills/bigquery-ml/syntax/mlforecast.md +76 -0
  223. bigquery_data_science/_skills/bigquery-ml/syntax/mlgenerate_embedding-from-a-bqml-pca-autoencoder-matrix_factorization-model.md +64 -0
  224. bigquery_data_science/_skills/bigquery-ml/syntax/mlglobal_explain.md +63 -0
  225. bigquery_data_science/_skills/bigquery-ml/syntax/mlhash_bucketize.md +47 -0
  226. bigquery_data_science/_skills/bigquery-ml/syntax/mlholiday_info.md +46 -0
  227. bigquery_data_science/_skills/bigquery-ml/syntax/mlimputer.md +46 -0
  228. bigquery_data_science/_skills/bigquery-ml/syntax/mllp_norm.md +47 -0
  229. bigquery_data_science/_skills/bigquery-ml/syntax/mlmetrics.md +80 -0
  230. bigquery_data_science/_skills/bigquery-ml/syntax/mlngrams.md +37 -0
  231. bigquery_data_science/_skills/bigquery-ml/syntax/mlone_hot_encoder-mlmulti_hot_encoder-mllabel_encoder.md +67 -0
  232. bigquery_data_science/_skills/bigquery-ml/syntax/mlpolynomial_expand.md +47 -0
  233. bigquery_data_science/_skills/bigquery-ml/syntax/mlpredict.md +67 -0
  234. bigquery_data_science/_skills/bigquery-ml/syntax/mlprincipal_component_info.md +42 -0
  235. bigquery_data_science/_skills/bigquery-ml/syntax/mlprincipal_components.md +40 -0
  236. bigquery_data_science/_skills/bigquery-ml/syntax/mlquantile_bucketize.md +43 -0
  237. bigquery_data_science/_skills/bigquery-ml/syntax/mlrecommend.md +60 -0
  238. bigquery_data_science/_skills/bigquery-ml/syntax/mlreconstruction_loss.md +48 -0
  239. bigquery_data_science/_skills/bigquery-ml/syntax/mlresize_image.md +45 -0
  240. bigquery_data_science/_skills/bigquery-ml/syntax/mlroc_curve.md +63 -0
  241. bigquery_data_science/_skills/bigquery-ml/syntax/mltf_idf.md +37 -0
  242. bigquery_data_science/_skills/bigquery-ml/syntax/mltfdv_describe.md +34 -0
  243. bigquery_data_science/_skills/bigquery-ml/syntax/mltfdv_validate.md +48 -0
  244. bigquery_data_science/_skills/bigquery-ml/syntax/mltraining_info.md +78 -0
  245. bigquery_data_science/_skills/bigquery-ml/syntax/mltransform-applying-a-saved-transform.md +52 -0
  246. bigquery_data_science/_skills/bigquery-ml/syntax/mltranspose-not-a-function-pointer.md +32 -0
  247. bigquery_data_science/_skills/bigquery-ml/syntax/mltrial_info.md +60 -0
  248. bigquery_data_science/_skills/bigquery-ml/syntax/mlvalidate_data_drift.md +99 -0
  249. bigquery_data_science/_skills/bigquery-ml/syntax/mlvalidate_data_skew.md +50 -0
  250. bigquery_data_science/_skills/bigquery-ml/syntax/mlweights.md +84 -0
  251. bigquery_data_science/_skills/bigquery-ml/syntax/model-free-time-series-decomposition-mltrend-mlseasonality-mldetect_change_points.md +100 -0
  252. bigquery_data_science/_skills/bigquery-ml/syntax/model-introspection-mlfeature_info-mltraining_info-mltrial_info.md +7 -0
  253. bigquery_data_science/_skills/bigquery-ml/syntax/model-monitoring-data-validation.md +23 -0
  254. bigquery_data_science/_skills/bigquery-ml/syntax/numerical-scalers-mlstandard_scaler-mlmin_max_scaler-mlmax_abs_scaler-mlrobust_scaler-mlnormalizer.md +77 -0
  255. bigquery_data_science/_skills/bigquery-ml/syntax/onnx.md +55 -0
  256. bigquery_data_science/_skills/bigquery-ml/syntax/pca.md +91 -0
  257. bigquery_data_science/_skills/bigquery-ml/syntax/point-in-time-feature-retrieval-mlfeatures_at_time-mlentity_features_at_time.md +25 -0
  258. bigquery_data_science/_skills/bigquery-ml/syntax/quick-comparison.md +14 -0
  259. bigquery_data_science/_skills/bigquery-ml/syntax/random_forest_classifier-random_forest_regressor.md +123 -0
  260. bigquery_data_science/_skills/bigquery-ml/syntax/remote-remote-model-over-a-vertex-ai-endpoint-the-mechanism.md +87 -0
  261. bigquery_data_science/_skills/bigquery-ml/syntax/tensorflow.md +48 -0
  262. bigquery_data_science/_skills/bigquery-ml/syntax/tensorflow_lite.md +29 -0
  263. bigquery_data_science/_skills/bigquery-ml/syntax/text-preprocessing-functions-mlngrams-mltf_idf-mlbag_of_words.md +18 -0
  264. bigquery_data_science/_skills/bigquery-ml/syntax/timesfm-built-in-foundation-forecaster-see-bigquery-ai.md +28 -0
  265. bigquery_data_science/_skills/bigquery-ml/syntax/transform_only.md +91 -0
  266. bigquery_data_science/_skills/bigquery-ml/syntax/xgboost.md +72 -0
  267. bigquery_data_science/_skills/pinned-models.json +28 -0
  268. bigquery_data_science/catalog.py +1107 -0
  269. bigquery_data_science/cli.py +786 -0
  270. bigquery_data_science/installer.py +282 -0
  271. bigquery_data_science/mcp_server.py +317 -0
  272. bigquery_data_science/tooling/__init__.py +15 -0
  273. bigquery_data_science/tooling/convert_notebook.py +176 -0
  274. bigquery_data_science/tooling/link_policy.py +247 -0
  275. bigquery_data_science/tooling/manifest.py +152 -0
  276. bigquery_data_science/tooling/markdown_anchors.py +84 -0
  277. bigquery_data_science/tooling/narrative_drift.py +163 -0
  278. bigquery_data_science/tooling/pinned_models.py +216 -0
  279. bigquery_data_science/tooling/reference_structure.py +85 -0
  280. bigquery_data_science/tooling/sync_syntax.py +407 -0
  281. bigquery_data_science/tooling/validate.py +208 -0
  282. bigquery_data_science-0.7.0.dist-info/METADATA +306 -0
  283. bigquery_data_science-0.7.0.dist-info/RECORD +286 -0
  284. bigquery_data_science-0.7.0.dist-info/WHEEL +4 -0
  285. bigquery_data_science-0.7.0.dist-info/entry_points.txt +5 -0
  286. bigquery_data_science-0.7.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,437 @@
1
+ > **Source (`statmike/bigquery-data-science`):** **Notebook:** [`bigquery-ai/functions/ai_forecast/ai_forecast.ipynb`](https://github.com/statmike/bigquery-data-science/blob/main/bigquery-ai/functions/ai_forecast/ai_forecast.ipynb) · **SQL:** [`bigquery-ai/functions/ai_forecast/ai_forecast.sql`](https://github.com/statmike/bigquery-data-science/blob/main/bigquery-ai/functions/ai_forecast/ai_forecast.sql)
2
+
3
+ # AI.FORECAST — BigQuery AI Functions
4
+
5
+ `AI.FORECAST` is a table-valued function that forecasts future time series values using BigQuery ML's built-in TimesFM model. No model creation or training required. Univariate forecasting is GA; multivariate forecasting and the TimesFM 3.0 model are Preview.
6
+
7
+ **When to use it:**
8
+ - You want to forecast future values from historical time series data
9
+ - You need prediction intervals (confidence bounds) for forecasts
10
+ - You want to forecast multiple independent time series at once
11
+ - You need a zero-setup forecasting solution (no CREATE MODEL)
12
+ - You can specify a target date with `forecast_end_timestamp` instead of a numeric `horizon`
13
+ - You can control how much history the model sees with `context_window` (64–15,360 on TimesFM 2.5; 64–2,048 on TimesFM 3.0)
14
+ - You have related series to forecast together, or covariates that should shape the forecast — TimesFM 3.0 (Preview) adds multivariate forecasting with `target_cols`, `past_covariate_cols` and `future_covariate_cols`
15
+
16
+ **Alternatives:**
17
+ - `functions/ai_detect_anomalies` (`AI.DETECT_ANOMALIES`) — Detect anomalies by comparing data against a forecast baseline
18
+ - `functions/ai_evaluate` (`AI.EVALUATE`) — Evaluate forecast accuracy against actual values
19
+ - `bigquery-ml/models/arima_plus` (`ARIMA_PLUS`) — the trainable, in-BigQuery classical statistical alternative: custom holiday effects, hierarchical reconciliation across a real dimension hierarchy, decomposable and explainable components (`ML.EXPLAIN_FORECAST`), and forecast bounds — none of which the TimesFM functions expose. External regressors are no longer the dividing line: `bigquery-ml/models/arima_plus_xreg` (`ARIMA_PLUS_XREG`) and TimesFM 3.0's covariates (section 9 below) both take them. Use `AI.FORECAST` for a fast, no-training baseline — with 3.0, a covariate-aware one; reach for `ARIMA_PLUS` when you need that level of control and explanation.
20
+ - `bigquery-ml/functions/time_series` (`ML.TREND` / `ML.SEASONALITY` / `ML.DETECT_CHANGE_POINTS`) — model-free decomposition rather than forecasting: trend, seasonal components, and sustained structural change points, with no `CREATE MODEL` and no foundation model. Reach for these when the question is *what has this series been doing* rather than *what will it do next*.
21
+ - `bigquery-ml/workflows/causal_effect` (`AI.CAUSAL_EFFECT`) — **the same forecasting idea aimed backwards.** It is not TimesFM: it wraps `ARIMA_PLUS`, and the sibling notebook reproduces its counterfactual bit-for-bit with a plain `CREATE MODEL ... ARIMA_PLUS`. Instead of forecasting past the end of the data, it forecasts past a point *inside* the data — the intervention date — and reports how far the observed values ran from that counterfactual. Reach for it when the question is *what would have happened without the change*, and for `AI.FORECAST` when the question is *what happens next*.
22
+
23
+ **Featured in:** `workflows/time_series_intelligence` (Time Series Intelligence)
24
+
25
+ **References:** `RESOURCES.md` (Full syntax reference) | [Official documentation](https://cloud.google.com/bigquery/docs/reference/standard-sql/bigqueryml-syntax-ai-forecast) | `setup` (Setup guide)
26
+
27
+ ---
28
+ ## Setup
29
+
30
+ Set your project and location, authenticate, and create a temporary dataset for this notebook.
31
+
32
+ > This function doesn't require a connection or model — it uses end-user credentials automatically. See the `setup` (Setup Reference) for details.
33
+
34
+ ```python
35
+ PROJECT_ID = 'statmike-mlops-349915' # <-- Replace with your project ID
36
+ LOCATION = 'US' # BigQuery dataset location
37
+ DATASET_ID = 'bq_ai_functions' # Shared dataset across all notebooks
38
+ ```
39
+
40
+ ### Environment
41
+
42
+ > **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.
43
+ >
44
+ > **Running standalone** (Colab, Colab Enterprise, Vertex AI Workbench)? The cell below installs required packages into your current kernel.
45
+
46
+ ```python
47
+ from google.cloud import bigquery
48
+ import pandas as pd
49
+
50
+ client = bigquery.Client(project=PROJECT_ID)
51
+ pd.set_option('display.max_colwidth', None)
52
+
53
+ # Create the shared dataset (idempotent)
54
+ dataset_ref = bigquery.DatasetReference(PROJECT_ID, DATASET_ID)
55
+ dataset = bigquery.Dataset(dataset_ref)
56
+ dataset.location = LOCATION
57
+ client.create_dataset(dataset, exists_ok=True)
58
+ print(f'Dataset {PROJECT_ID}.{DATASET_ID} ready')
59
+
60
+ # Register %%bigquery cell magic (auto-loaded in Colab, needed elsewhere)
61
+ %load_ext bigquery_magics
62
+ ```
63
+
64
+ ---
65
+ ## Examples — SQL
66
+
67
+ Progressive examples from simplest to most advanced. Each cell adds one new concept.
68
+
69
+ ### Setup: Create sample time series data
70
+
71
+ Generate synthetic daily sales data with realistic patterns using SQL.
72
+
73
+ ```python
74
+ # Create synthetic daily sales data with trend and weekly seasonality
75
+ query = f'''
76
+ CREATE OR REPLACE TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales` AS
77
+ WITH dates AS (
78
+ SELECT date
79
+ FROM UNNEST(GENERATE_DATE_ARRAY('2024-01-01', '2024-12-31')) AS date
80
+ )
81
+ SELECT
82
+ date,
83
+ -- Base sales + trend + weekly seasonality + noise
84
+ GREATEST(0,
85
+ 1000
86
+ + EXTRACT(DAYOFYEAR FROM date) * 2 -- upward trend
87
+ + CASE EXTRACT(DAYOFWEEK FROM date)
88
+ WHEN 1 THEN -200 -- Sunday dip
89
+ WHEN 7 THEN 300 -- Saturday peak
90
+ WHEN 6 THEN 200 -- Friday boost
91
+ ELSE 0
92
+ END
93
+ + CAST(200 * (RAND() - 0.5) AS INT64) -- random noise
94
+ ) AS daily_sales
95
+ FROM dates
96
+ '''
97
+ client.query(query).result()
98
+
99
+ # Preview the data
100
+ df = client.query(f'SELECT * FROM `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales` ORDER BY date LIMIT 10').to_dataframe()
101
+ print(f'Rows: {client.query(f"SELECT COUNT(*) AS n FROM `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`").to_dataframe().iloc[0]["n"]}')
102
+ df
103
+ ```
104
+
105
+ ### 1. Basic forecast
106
+
107
+ `AI.FORECAST` requires `data_col` and `timestamp_col`. Default horizon is 10 time steps.
108
+
109
+ ```python
110
+ query = f'''
111
+ SELECT *
112
+ FROM AI.FORECAST(
113
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`,
114
+ data_col => 'daily_sales',
115
+ timestamp_col => 'date'
116
+ )
117
+ '''
118
+ client.query(query).to_dataframe()
119
+ ```
120
+
121
+ ### 2. Custom horizon
122
+
123
+ Forecast more time steps into the future.
124
+
125
+ ```python
126
+ query = f'''
127
+ SELECT *
128
+ FROM AI.FORECAST(
129
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`,
130
+ data_col => 'daily_sales',
131
+ timestamp_col => 'date',
132
+ horizon => 30
133
+ )
134
+ '''
135
+ client.query(query).to_dataframe()
136
+ ```
137
+
138
+ ### 3. Include historical data
139
+
140
+ Set `output_historical_time_series => TRUE` to get historical + forecasted data in one result for comparison.
141
+
142
+ ```python
143
+ query = f'''
144
+ SELECT *
145
+ FROM AI.FORECAST(
146
+ (SELECT * FROM `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`
147
+ WHERE date >= '2024-11-01'), -- last 2 months for context
148
+ data_col => 'daily_sales',
149
+ timestamp_col => 'date',
150
+ horizon => 14,
151
+ output_historical_time_series => TRUE
152
+ )
153
+ ORDER BY time_series_timestamp
154
+ '''
155
+ df = client.query(query).to_dataframe()
156
+ print(f'Historical rows: {(df["time_series_type"] == "history").sum()}')
157
+ print(f'Forecast rows: {(df["time_series_type"] == "forecast").sum()}')
158
+ df.tail(20)
159
+ ```
160
+
161
+ ### 4. Multi-series forecasting with id_cols
162
+
163
+ Forecast multiple independent time series at once by specifying `id_cols`.
164
+
165
+ ```python
166
+ # Create multi-series data
167
+ query = f'''
168
+ CREATE OR REPLACE TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_multi_series` AS
169
+ WITH dates AS (
170
+ SELECT date
171
+ FROM UNNEST(GENERATE_DATE_ARRAY('2024-01-01', '2024-12-31')) AS date
172
+ ),
173
+ stores AS (
174
+ SELECT * FROM UNNEST([
175
+ STRUCT('downtown' AS store_id, 1500 AS base_sales),
176
+ STRUCT('suburban', 800),
177
+ STRUCT('airport', 2000)
178
+ ])
179
+ )
180
+ SELECT
181
+ s.store_id,
182
+ d.date,
183
+ GREATEST(0, s.base_sales + EXTRACT(DAYOFYEAR FROM d.date) * 1 + CAST(100 * (RAND() - 0.5) AS INT64)) AS daily_sales
184
+ FROM dates d CROSS JOIN stores s
185
+ '''
186
+ client.query(query).result()
187
+ print('Multi-series data created')
188
+ ```
189
+
190
+ ```python
191
+ # Forecast each store independently
192
+ query = f'''
193
+ SELECT *
194
+ FROM AI.FORECAST(
195
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_multi_series`,
196
+ data_col => 'daily_sales',
197
+ timestamp_col => 'date',
198
+ id_cols => ['store_id'],
199
+ horizon => 14
200
+ )
201
+ ORDER BY store_id, forecast_timestamp
202
+ '''
203
+ client.query(query).to_dataframe()
204
+ ```
205
+
206
+ ### 5. Confidence level and TimesFM model version
207
+
208
+ Control prediction interval width with `confidence_level`, and pin the model version with `model`.
209
+
210
+ **The default is TimesFM 2.5.** The other accepted value is `'TimesFM 3.0'` (Preview) — section 8 covers what it adds. Pin `model` whenever the numbers have to be reproducible: an unpinned call follows the default, and the default moves when Google advances it.
211
+
212
+ ```python
213
+ query = f'''
214
+ SELECT *
215
+ FROM AI.FORECAST(
216
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`,
217
+ data_col => 'daily_sales',
218
+ timestamp_col => 'date',
219
+ horizon => 14,
220
+ confidence_level => 0.99,
221
+ model => 'TimesFM 2.5'
222
+ )
223
+ '''
224
+ client.query(query).to_dataframe()
225
+ ```
226
+
227
+ ### 6. Forecast to a specific date
228
+
229
+ Use `forecast_end_timestamp` instead of `horizon` to forecast up to a target date. The horizon is calculated automatically from the data's frequency. Mutually exclusive with `horizon`.
230
+
231
+ ```python
232
+ query = f'''
233
+ SELECT *
234
+ FROM AI.FORECAST(
235
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`,
236
+ data_col => 'daily_sales',
237
+ timestamp_col => 'date',
238
+ forecast_end_timestamp => '2025-01-15'
239
+ )
240
+ '''
241
+ df = client.query(query).to_dataframe()
242
+ print(f'Forecasted {len(df)} days (through {df["forecast_timestamp"].max().strftime("%Y-%m-%d")})')
243
+ df
244
+ ```
245
+
246
+ ### 7. Setting the context window
247
+
248
+ The `context_window` controls how many of the most recent historical points the model sees. The two model versions handle it differently:
249
+
250
+ - **TimesFM 2.5** (default): 64, 128, 256, 512, 1024, 2048, 4096, 8192 or 15360. When unspecified, the smallest window covering your data is auto-selected. Any other value is rejected.
251
+ - **TimesFM 3.0**: a multiple of 32 from 64 to 2048. When unspecified, the **maximum** (2048) is used, and points older than that are ignored. A value above 2048 is rejected; a value that is not a multiple of 32 is accepted rather than rejected, so stay on the documented grid if you want to know what the model saw.
252
+
253
+ ```python
254
+ query = f'''
255
+ SELECT
256
+ forecast_timestamp,
257
+ ROUND(forecast_value, 0) AS forecast,
258
+ ROUND(prediction_interval_lower_bound, 0) AS lower,
259
+ ROUND(prediction_interval_upper_bound, 0) AS upper
260
+ FROM AI.FORECAST(
261
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales`,
262
+ data_col => 'daily_sales',
263
+ timestamp_col => 'date',
264
+ horizon => 7,
265
+ context_window => 128
266
+ )
267
+ '''
268
+ client.query(query).to_dataframe()
269
+ ```
270
+
271
+ ### 8. TimesFM 3.0 (Preview): multivariate forecasting with `target_cols`
272
+
273
+ TimesFM 3.0 is selected with `model => 'TimesFM 3.0'`. On a single series it is a drop-in alternative to 2.5 with the same output columns, and a shorter reach: `horizon` is capped at 1,024 and the context window at 2,048 points.
274
+
275
+ What it adds is **multivariate forecasting**: pass `target_cols` (an array of column names) instead of `data_col`, and the model forecasts the series jointly. This syntax requires `model => 'TimesFM 3.0'` — with any other model, or with no `model` at all, the call fails with the generic `Invalid table-valued function AI.FORECAST`.
276
+
277
+ The output is restructured for multiple targets:
278
+ - the timestamp column **keeps its input name** (`date` here, not `forecast_timestamp`) and comes back as a `TIMESTAMP`
279
+ - each target becomes a `STRUCT<value, prediction_interval_lower_bound, prediction_interval_upper_bound>` under its own name
280
+ - `time_series_type` (`forecast`, or `history` when `output_historical_time_series => TRUE`), `confidence_level` and `ai_forecast_status` complete the row
281
+
282
+ `forecast_end_timestamp` is accepted in this form too, although the documented multivariate syntax lists only `horizon`.
283
+
284
+ First, a second table with two related daily series — sales and web visits — plus two columns that will serve as covariates in section 9. It covers 2024 as history and includes **14 future dates with the targets left NULL**; section 9 explains why.
285
+
286
+ ```python
287
+ # Two related daily series (sales, web visits) plus two covariates (promo flag, weekend flag).
288
+ # History: 2024. Future: 14 days with the targets NULL and the future covariates populated.
289
+ query = f'''
290
+ CREATE OR REPLACE TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales_mv` AS
291
+ WITH days AS (
292
+ SELECT date,
293
+ EXTRACT(DAYOFWEEK FROM date) AS dow,
294
+ DATE_DIFF(date, DATE '2024-01-01', DAY) AS t
295
+ FROM UNNEST(GENERATE_DATE_ARRAY('2024-01-01', '2025-01-14')) AS date
296
+ )
297
+ SELECT
298
+ date,
299
+ IF(date <= '2024-12-31', GREATEST(0,
300
+ 1000 + t * 2
301
+ + CASE dow WHEN 1 THEN -200 WHEN 7 THEN 300 WHEN 6 THEN 200 ELSE 0 END
302
+ + IF(MOD(t + 20, 30) < 3, 400, 0) -- promotion lift
303
+ + CAST(200 * (RAND() - 0.5) AS INT64)), NULL) AS daily_sales,
304
+ IF(date <= '2024-12-31', GREATEST(0,
305
+ 5000 + t * 5
306
+ + CASE dow WHEN 1 THEN -800 WHEN 7 THEN 1200 WHEN 6 THEN 800 ELSE 0 END
307
+ + CAST(600 * (RAND() - 0.5) AS INT64)), NULL) AS web_visits,
308
+ IF(MOD(t + 20, 30) < 3, 1, 0) AS promo_flag, -- known in advance: the promotion calendar
309
+ IF(dow IN (1, 7), 1, 0) AS is_weekend -- known in advance: the calendar
310
+ FROM days
311
+ '''
312
+ client.query(query).result()
313
+
314
+ # The seam between history and future: targets stop, future covariates continue
315
+ df = client.query(f'''
316
+ SELECT * FROM `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales_mv`
317
+ WHERE date BETWEEN '2024-12-29' AND '2025-01-03' ORDER BY date''').to_dataframe()
318
+ df
319
+ ```
320
+
321
+ Forecast both series jointly from the history rows. Each target comes back as its own `STRUCT`; the query below flattens the fields it wants.
322
+
323
+ ```python
324
+ query = f'''
325
+ SELECT
326
+ date,
327
+ ROUND(daily_sales.value) AS sales_forecast,
328
+ ROUND(daily_sales.prediction_interval_lower_bound) AS sales_lower,
329
+ ROUND(daily_sales.prediction_interval_upper_bound) AS sales_upper,
330
+ ROUND(web_visits.value) AS visits_forecast,
331
+ time_series_type,
332
+ ai_forecast_status
333
+ FROM AI.FORECAST(
334
+ (SELECT date, daily_sales, web_visits
335
+ FROM `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales_mv`
336
+ WHERE date <= '2024-12-31'),
337
+ target_cols => ['daily_sales', 'web_visits'],
338
+ timestamp_col => 'date',
339
+ model => 'TimesFM 3.0',
340
+ horizon => 7
341
+ )
342
+ ORDER BY date
343
+ '''
344
+ client.query(query).to_dataframe()
345
+ ```
346
+
347
+ ### 9. Past and future covariates
348
+
349
+ Covariates are extra columns the model may use to shape the forecast. TimesFM 3.0 distinguishes two kinds by *when they are known*:
350
+
351
+ - **`past_covariate_cols`** — known only historically. Web visits influence sales, but tomorrow's visits are not known today: populated for history rows, NULL for the future rows.
352
+ - **`future_covariate_cols`** — known for the past *and* the future. The promotion calendar and the day of the week are fixed in advance: populated on every row, including the 14 future dates.
353
+
354
+ That is why the input table carries future rows with NULL targets: the future covariates have to be supplied for every timestamp you want forecast. Covariates require the `target_cols` form — `data_col` plus a covariate argument is rejected. Three things measured here that the syntax does not say:
355
+
356
+ - `horizon` is **capped by the future rows you supply** — ask for 30 with 14 future rows and you get 14, silently.
357
+ - Without `horizon`, the default of 10 applies even when more future rows are available.
358
+ - A past covariate alone, with no future rows at all, also works — it simply conditions the forecast on the history.
359
+
360
+ ```python
361
+ query = f'''
362
+ WITH forecast AS (
363
+ SELECT
364
+ date,
365
+ ROUND(daily_sales.value) AS sales_forecast,
366
+ ROUND(daily_sales.prediction_interval_lower_bound) AS lower,
367
+ ROUND(daily_sales.prediction_interval_upper_bound) AS upper
368
+ FROM AI.FORECAST(
369
+ TABLE `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales_mv`,
370
+ target_cols => ['daily_sales'],
371
+ timestamp_col => 'date',
372
+ model => 'TimesFM 3.0',
373
+ horizon => 14,
374
+ past_covariate_cols => ['web_visits'],
375
+ future_covariate_cols => ['promo_flag', 'is_weekend']
376
+ )
377
+ )
378
+ SELECT f.date, f.sales_forecast, f.lower, f.upper, c.promo_flag, c.is_weekend
379
+ FROM forecast f
380
+ JOIN `{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales_mv` c ON DATE(f.date) = c.date
381
+ ORDER BY f.date
382
+ '''
383
+ client.query(query).to_dataframe()
384
+ ```
385
+
386
+ ---
387
+ ## Examples — `%%bigquery` Magics
388
+
389
+ The same examples using IPython magic commands. Magics let you write SQL directly in notebook cells without Python string wrapping.
390
+
391
+ Key patterns:
392
+ - `%%bigquery` — run SQL, display results inline
393
+ - `%%bigquery df` — run SQL, capture results into a pandas DataFrame
394
+
395
+ ### Basic forecast with `%%bigquery`
396
+
397
+ ```sql
398
+ %%bigquery --project {PROJECT_ID}
399
+
400
+ SELECT *
401
+ FROM AI.FORECAST(
402
+ TABLE `statmike-mlops-349915.bq_ai_functions.ai_forecast_sales`,
403
+ data_col => 'daily_sales',
404
+ timestamp_col => 'date',
405
+ horizon => 7
406
+ )
407
+ ```
408
+
409
+ ---
410
+ ## Examples — BigFrames
411
+
412
+ BigFrames wraps `AI.FORECAST` via `bbq.ai.forecast()`. No model object needed. Pass `model` explicitly: the wrapper's own default is `'TimesFM 2.0'`, a version the SQL reference page no longer lists, so an unpinned wrapper call and an unpinned SQL call run different models.
413
+
414
+ ```python
415
+ import bigframes.pandas as bpd
416
+ import bigframes.bigquery as bbq
417
+
418
+ bpd.options.bigquery.project = PROJECT_ID
419
+ bpd.options.bigquery.location = LOCATION
420
+ ```
421
+
422
+ ### Basic forecast
423
+
424
+ ```python
425
+ # Load the time series data
426
+ df = bpd.read_gbq(f'{PROJECT_ID}.{DATASET_ID}.ai_forecast_sales')
427
+
428
+ # Forecast
429
+ forecast = bbq.ai.forecast(
430
+ df,
431
+ data_col='daily_sales',
432
+ timestamp_col='date',
433
+ horizon=14,
434
+ model='TimesFM 2.5'
435
+ )
436
+ forecast.to_pandas()
437
+ ```