שימוש במנהל התקן JDBC ל-BigQuery

מנהל ההתקן (driver) של Java Database Connectivity‏ (JDBC) ל-BigQuery מקשר את אפליקציות Java ל-BigQuery, ומאפשר לכם להשתמש בתכונות של BigQuery עם כלי התשתית המועדפים שלכם. כדי לחבר אפליקציות שאינן Java ל-BigQuery, משתמשים במנהל התקן של Open Database Connectivity‏ (ODBC) ל-BigQuery.

מגבלות

מגבלות השימוש בדרייבר JDBC ל-BigQuery:

לפני שמתחילים

  1. חשוב לוודא שאתם מכירים את מנהלי ההתקנים של JDBC, את Apache Maven ואת חבילת java.sql.
  2. מוודאים שהמערכת מוגדרת עם סביבת זמן ריצה של Java‏ (JRE) בגרסה 8.0 ואילך. מידע על בדיקת גרסת ה-JRE זמין במאמר אימות סביבת ה-JRE.

  3. מאמתים את הזהות ב-BigQuery ורושמים את הפרטים הבאים, שבהם תשתמשו בהמשך כשתקימו חיבור עם מנהל ההתקן של JDBC ל-BigQuery. צריך לציין רק את המידע שמתאים לשיטת האימות שבה אתם משתמשים.

    שיטת אימות פרטי אימות דוגמה מאפיין של חיבור (להגדרה בהמשך)
    חשבון שירות רגיל כתובת האימייל של חשבון השירות bq-jdbc-sa@mytestproject. OAuthServiceAcctEmail
    מפתח של חשבון שירות (אובייקט JSON) my-sa-key OAuthPvtKey
    קובץ מפתח של חשבון שירות קובץ המפתח של חשבון השירות (נתיב מלא) path/to/file/secret.json OAuthPvtKeyPath
    חשבון משתמש ב-Google מזהה לקוח 123-abc.apps.googleusercontent.com OAuthClientId
    סוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    טוקן גישה שנוצר מראש טוקן גישה ya29.a0AfH6SMCiH1L-x_yZ OAuthAccessToken
    טוקן רענון שנוצר מראש טוקן רענון 1/fFAGRNJru1FTz70BzhT3Zg OAuthRefreshToken
    מזהה לקוח 123-abc.apps.googleusercontent.com OAuthClientId
    סוד לקוח _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Application Default Credentials ללא לא רלוונטי לא רלוונטי
    קובץ תצורה קובץ תצורה (אובייקט JSON או נתיב מלא) path/to/file/secret.json OAuthPvtKey
    אובייקט הגדרת חשבון חיצוני אובייקט של הגדרת חשבון external_account_configuration_object OAuthPvtKey
    אחר מאפיין הקהל של קובץ ההגדרה של החשבון החיצוני //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider BYOID_AudienceUri
    אחזור טוקן וקובץ מידע על הסביבה {\"file\":\"/path/to/file\"} BYOID_CredentialSource
    פרויקט של משתמש (רק אם משתמשים במאגר כוח עבודה) my_project BYOID_PoolUserProject
    ה-URI להתחזות לחשבון שירות (רק אם משתמשים במאגר כוח אדם) my-sa BYOID_SA_Impersonation_Uri
    אסימון Security Token Service שמבוסס על מפרט החלפת האסימונים urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    נקודת הקצה להחלפת טוקנים של Security Token Service https://sts.googleapis.com/v1/token BYOID_TokenUri

התקנה והגדרה של מנהל ההתקן של JDBC

אפשר להתקין ולהגדיר את מנהל ההתקן JDBC ל-BigQuery על ידי הורדה ישירה של קובץ ה-JAR הגדול או באמצעות Maven.

הגדרת הורדה ישירה

כדי להגדיר את מנהל ההתקן של JDBC באמצעות הורדה ישירה:

  1. מורידים את גרסה 1.1.0 של הדרייבר.
  2. מעתיקים את הקובץ שהורדתם למיקום שצוין בתוכנה.

מידע על שינויים בתכונות ועדכונים בתהליכי העבודה זמין ביומן השינויים.

הגדרת Maven

מנהל ההתקן של JDBC ל-BigQuery זמין ב-Maven Central.

כדי להגדיר את סביבת הפיתוח באמצעות מנהל ההתקן JDBC, מוסיפים את מנהל ההתקן כתלות לפרויקט:

Maven

מוסיפים את יחסי התלות הבאים לקובץ pom.xml:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.1.0</version>
</dependency>

‫Maven באמצעות uber-JAR

מוסיפים את יחסי התלות הבאים לקובץ pom.xml:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.1.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

Gradle

מוסיפים לקובץ build.gradle את הנתונים הבאים:

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.1.0")
}

יצירת חיבור

כדי ליצור חיבור בין אפליקציית Java לבין BigQuery באמצעות מנהל התקן JDBC ל-BigQuery, צריך לבצע את הפעולות הבאות:

  1. מזהים את מחרוזת החיבור של מנהל ההתקן של JDBC ל-BigQuery. המחרוזת הזו כוללת את כל המידע שנדרש כדי ליצור חיבור בין אפליקציית Java לבין BigQuery. מחרוזת החיבור היא בפורמט הבא:

    jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫HOST: כתובת ה-DNS או כתובת ה-IP של השרת.
    • ‫PORT: מספר יציאת ה-TCP.
    • ‫PROJECT_ID: מזהה הפרויקט ב-BigQuery.
    • ‫AUTH_TYPE: מספר שמציין את סוג האימות שבו השתמשתם. אחת מהאפשרויות הבאות:
      • ‫0: לאימות של חשבון שירות (סטנדרטי וקובץ מפתח)
      • ‫1: לאימות של חשבון משתמש ב-Google
      • ‫2: לאימות של אסימון גישה או רענון שנוצר מראש
      • ‫3: לאימות באמצעות Application Default Credential
      • ‫4: לשיטות אימות אחרות
    • ‫AUTH_PROPS: פרטי האימות שרשמתם כשהזדהיתם ב-BigQuery, שמופיעים בפורמט property_1=value_1; property_2=value_2;... – לדוגמה, OAuthPvtKeyPath=path/to/file/secret.json, אם הזדהיתם באמצעות קובץ מפתח של חשבון שירות.
    • ‫OTHER_PROPS (אופציונלי): מאפייני חיבור נוספים למנהל התקן JDBC, שמופיעים בפורמט property_1=value_1; property_2=value_2;.... רשימה מלאה של מאפייני החיבור זמינה במאמר בנושא מאפייני חיבור.

  2. מחברים את אפליקציית Java למנהל ההתקן של JDBC ל-BigQuery באמצעות המחלקה DriverManager או DataSource.

    • מתחברים לכיתה DriverManager:

      import java.sql.Connection;
import java.sql.DriverManager;

private static Connection getJdbcConnectionDM(){
  Connection connection = DriverManager.getConnection(CONNECTION_STRING);
  return connection;
}

      מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

    • מתחברים לכיתה DataSource:

      import com.google.cloud.bigquery.jdbc.DataSource;
import java.sql.Connection;
import java.sql.SQLException;

private static public Connection getJdbcConnectionDS() throws SQLException {
  Connection connection = null;
  DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
  dataSource.setURL(CONNECTION_STRING);
  connection = dataSource.getConnection();
  return connection;
}

      מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

      במחלקה DataSource יש גם שיטות setter שבהן אפשר להשתמש כדי להגדיר מאפייני חיבור, במקום לכלול אותם במחרוזת החיבור. לדוגמה:

      private static Connection getConnection() throws SQLException {
  DataSource ds = new DataSource();
  ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
  ds.setAuthType(3);  // Application Default Credentials
  ds.setProjectId("MyTestProject");
  ds.setEnableHighThroughputAPI(true);
  ds.setLogLevel("6");
  ds.setUseQueryCache(false);
  return ds.getConnection();
}

מאפייני החיבור

מאפייני החיבור של מנהל ההתקן JDBC הם פרמטרים של הגדרה שכוללים במחרוזת החיבור או מעבירים דרך שיטות setter כשמקימים חיבור למסד נתונים. מנהל ההתקן של JDBC ל-BigQuery תומך במאפייני החיבור הבאים.

נכס חיבור תיאור ערך ברירת המחדל סוג הנתונים חובה
AdditionalProjects פרויקטים שלמנהל ההתקן יש גישה אליהם לשאילתות ולפעולות מטא-נתונים, בנוסף לפרויקט הראשי שהוגדר על ידי המאפיין ProjectId. לא רלוונטי מחרוזת מופרדת בפסיקים לא
AllowLargeResults קובע אם הדרייבר מעבד תוצאות של שאילתות שגדולות מ-128MB, כשהמאפיין QueryDialect מוגדר ל-BIG_QUERY. אם המאפיין QueryDialect מוגדר לערך SQL, מנהל ההתקן תמיד מעבד תוצאות גדולות של שאילתות. TRUE בוליאני לא
BYOID_AudienceUri מאפיין הקהל בקובץ ההגדרה של חשבון חיצוני. ‫ מאפיין הקהל יכול להכיל את שם המשאב של מאגר הזהויות של עומסי העבודה או של מאגר כוח העבודה, וגם את מזהה הספק במאגר הזה. לא רלוונטי String רק כשOAuthType=4
BYOID_CredentialSource אחזור הטוקן ופרטי הסביבה. לא רלוונטי String רק כשOAuthType=4
BYOID_PoolUserProject פרויקט המשתמש כשמשתמשים במאגר כוח עבודה לאימות. לא רלוונטי String רק כשמשתמשים ב-OAuthType=4 ובמאגר כוח העבודה
BYOID_SA_Impersonation_Uri ה-URI של ההתחזות לחשבון השירות כשמשתמשים במאגר כוח אדם לצורך אימות. לא רלוונטי String רק כשמשתמשים ב-OAuthType=4 ובמאגר כוח העבודה
BYOID_SubjectTokenType אסימון Security Token Service שמבוסס על מפרט החלפת האסימונים. אחת מהאפשרויות הבאות:
  • urn:ietf:params:oauth:token-type:jwt
  • urn:ietf:params:oauth:token-type:id_token
  • urn:ietf:params:oauth:token-type:saml2
  • urn:ietf:params:aws:token-type:aws4_request
 urn:ietf:params:oauth:tokentype:id_token String רק כשOAuthType=4
BYOID_TokenUri נקודת הקצה של החלפת האסימון של Security Token Service. https://sts.googleapis.com/v1/token String לא
ConnectionPoolSize גודל מאגר החיבורים, אם מאגר החיבורים מופעל. 10 ארוכה לא
DefaultDataset מערך הנתונים שמשמש את המערכת כשלא מציינים מערך נתונים בשאילתה. לא רלוונטי String לא
EnableGcpLogExporter ההגדרה הזו קובעת אם מנהל ההתקן מייצא באופן אוטומטי יומנים אל Cloud Logging (אם לא נעשה שימוש במופע OpenTelemetry גלובלי או בהתאמה אישית). מידע נוסף זמין במאמר בנושא OpenTelemetry. FALSE בוליאני לא
EnableGcpTraceExporter ההגדרה קובעת אם מנהל ההתקן מייצא אוטומטית עקבות ל-Cloud Trace (אם לא נעשה שימוש במופע OpenTelemetry בהתאמה אישית או במופע גלובלי). מידע נוסף זמין במאמר בנושא OpenTelemetry. FALSE בוליאני לא
EnableHighThroughputAPI קובעת אם אפשר להשתמש ב-Storage Read API. כדי להשתמש ב-Storage Read API, צריך להגדיר את המאפיינים HighThroughputActivationRatio ו-HighThroughputMinTableSize לערך TRUE. FALSE בוליאני לא
EnableProjectDiscovery ההגדרה קובעת אם שיטות של מטא-נתונים של מסד נתונים יגלו מערכי נתונים בכל הפרויקטים שאפשר לגשת אליהם Google Cloud . כשההגדרה היא FALSE, גילוי המשאבים מוגבל לברירת המחדל ProjectId. FALSE בוליאני לא
EnableSession קובע אם החיבור מתחיל סשן. אם הערך הוא TRUE, מזהה הסשן מועבר לכל השאילתות הבאות. FALSE בוליאני לא
EnableWriteAPI קובעת אם אפשר להשתמש ב-Storage Write API ‏ (gRPC). צריך להגדיר אותו לערך TRUE כדי להפעיל הוספה בכמות גדולה. FALSE בוליאני לא
EndpointOverrides נקודות קצה בהתאמה אישית כדי להחליף את נקודות הקצה הבאות:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
 לא רלוונטי מחרוזת מופרדת בפסיקים לא
FilterTablesOnDefaultDataset קובע את היקף המטא-נתונים שמוחזרים על ידי השיטות DatabaseMetaData.getTables() ו- DatabaseMetaData.getColumns(). אם הערך הוא FALSE, לא מתבצע סינון. כדי להפעיל את הסינון, צריך להגדיר גם את המאפיין DefaultDataset. FALSE בוליאני לא
GcpTelemetryCredentials פרטי הכניסה שמשמשים לאימות של כלי לייצוא טלמטריה. מקבל נתיב למפתח JSON של חשבון שירות או מחרוזת JSON גולמית. אם לא מגדירים ערך, ברירת המחדל היא פרטי הכניסה לחיבור. מידע נוסף זמין במאמר בנושא OpenTelemetry. לא רלוונטי String לא
GcpTelemetryProjectId מזהה הפרויקט של היעד Google Cloud לשימוש בטלמטריה. ברירת המחדל היא ProjectId הראשי. מידע נוסף זמין במאמר בנושא OpenTelemetry. לא רלוונטי String לא
HighThroughputActivationRatio סף מספר העמודים בתגובה לשאילתה. אם חורגים מהמספר הזה, והתנאים EnableHighThroughputAPI ו-HighThroughputMinTableSize מתקיימים, הנהג מתחיל להשתמש ב-Storage Read API. 2 מספר שלם לא
HighThroughputMinTableSize סף מספר השורות בתגובה לשאילתה. אם המספר הזה חורג מהמגבלה, והתנאים של EnableHighThroughputAPI ושל HighThroughputActivationRatio מתקיימים, ה-driver מתחיל להשתמש ב-Storage Read API. 10000 מספר שלם לא
JobCreationMode קובע אם השאילתות מופעלות עם משימות או בלי משימות. ערך של 1 מציין שנוצרות משימות לכל שאילתה, וערך של 2 מציין שאפשר להריץ שאילתות בלי משימות. 2 מספר שלם לא
JobTimeout הזמן הקצוב לתפוגה של המשימה (בשניות) שאחריו המשימה מבוטלת בשרת. 0 ארוכה לא
KMSKeyName השם של מפתח ה-KMS להצפנת נתונים. לא רלוונטי String לא
Labels תוויות שמשויכות לשאילתה כדי לארגן ולקבץ משימות של שאילתות. לא רלוונטי ‫Map<String, String> לא
LargeResultDataset ערכת הנתונים של היעד לתוצאות של שאילתות גדולות, רק אם המאפיין LargeResultTable מוגדר. כשמגדירים את המאפיין הזה, פעולות כתיבה של נתונים מדלגות על מטמון התוצאות ומפעילות חיוב על כל שאילתה, גם אם התוצאות קטנות. _google_jdbc String לא
LargeResultsDatasetExpirationTime משך החיים של כל הטבלאות במערך נתונים גדול של תוצאות, באלפיות השנייה. המערכת מתעלמת מהמאפיין הזה אם כבר הוגדר לערכת הנתונים זמן תפוגה שמוגדר כברירת מחדל. 3600000 ארוכה לא
LargeResultTable טבלת היעד של תוצאות שאילתה גדולות, רק אם המאפיין LargeResultDataset מוגדר. כשמגדירים את הנכס הזה, פעולות כתיבה של נתונים מדלגות על מטמון התוצאות ומפעילות חיוב על כל שאילתה, גם אם התוצאות קטנות. temp_table... String לא
ListenerPoolSize גודל מאגר המאזינים, אם מאגר החיבורים מופעל. 10 ארוכה לא
Location המיקום שבו נוצרים מערכי נתונים או נשלחות שאילתות לגביהם. אם לא מגדירים את הנכס הזה, BigQuery קובע את המיקום באופן אוטומטי. לא רלוונטי String לא
LogLevel רמת הפירוט שמתועדת על ידי הנהג. מידע נוסף זמין במאמר בנושא רישום ביומן. 0 מספר שלם לא
LogPath הספרייה שבה נכתבים קובצי היומן. לא רלוונטי String לא
MaximumBytesBilled מגבלת הבייטים לחיוב. אם השאילתה תחרוג ממגבלת הבייטים לחיוב, הרצת השאילתה תיכשל (החשבון לא יחויב). 0 ארוכה לא
MaxResults המספר המקסימלי של תוצאות בכל דף. 10000 ארוכה לא
MetaDataFetchThreadCount מספר השרשורים שמשמשים לשיטות של מטא-נתונים של מסד נתונים. 32 מספר שלם לא
OAuthAccessToken אסימון הגישה שמשמש לאימות של אסימון גישה שנוצר מראש. לא רלוונטי String רק כשOAUTH_TYPE=2
OAuthClientId מזהה הלקוח לאימות של טוקן רענון שנוצר מראש ולאימות של חשבון משתמש. לא רלוונטי String רק כשמזינים OAUTH_TYPE=1 או OAUTH_TYPE=2
OAuthClientSecret סוד הלקוח לאימות של טוקן רענון שנוצר מראש ולאימות של חשבון משתמש. לא רלוונטי String רק כשמזינים OAUTH_TYPE=1 או OAUTH_TYPE=2
OAuthP12Password הסיסמה לקובץ המפתח PKCS12. notasecret String לא
OAuthPvtKey המפתח של חשבון השירות כשמשתמשים באימות של חשבון שירות. הערך הזה יכול להיות אובייקט גולמי של קובץ מפתח JSON או נתיב לקובץ מפתח JSON. לא רלוונטי String רק כשהערך של OAUTH_TYPE=0 לא מוגדר וגם הערך של OAuthPvtKeyPath לא מוגדר
OAuthPvtKeyPath הנתיב למפתח של חשבון השירות כשמשתמשים באימות של חשבון שירות. לא רלוונטי String רק אם OAUTH_TYPE=0 והערכים של OAuthPvtKey ו-OAuthServiceAcctEmail לא מוגדרים
OAuthRefreshToken טוקן הרענון לאימות באמצעות טוקן רענון שנוצר מראש. לא רלוונטי String רק כשOAUTH_TYPE=2
OAuthServiceAcctEmail כתובת האימייל בחשבון השירות כשמשתמשים באימות של חשבון שירות. לא רלוונטי String רק כשהערך של OAUTH_TYPE=0 לא מוגדר וגם הערך של OAuthPvtKeyPath לא מוגדר
OAuthType סוג האימות. אחת מהאפשרויות הבאות:
  • 0: אימות של חשבון שירות
  • ‫1: אימות של חשבון המשתמש
  • 2: אימות באמצעות אסימון גישה או רענון שנוצר מראש
  • ‫3: אימות Application Default Credential
  • ‫4: שיטות אימות אחרות
 -1 מספר שלם כן
PartnerToken אסימון שמשמש שותפים של Google Cloud למעקב אחרי השימוש במנהל ההתקן. לא רלוונטי String לא
ProjectId מזהה הפרויקט שמוגדר כברירת מחדל לדרייבר. הפרויקט הזה משמש להרצת שאילתות, והחיוב על השימוש במשאבים מתבצע דרכו. אם לא מגדירים את מזהה הפרויקט, הדרייבר מסיק אותו. לא רלוונטי String לא, אבל מומלץ מאוד
ProxyHost שם המארח או כתובת ה-IP של שרת proxy שדרכו מנותב חיבור ה-JDBC. לא רלוונטי String לא
ProxyPort מספר היציאה שבה שרת ה-proxy מאזין לחיבורים. לא רלוונטי String לא
ProxyPwd הסיסמה לאימות כשמתחברים דרך שרת proxy שנדרש לכך. לא רלוונטי String לא
ProxyUid שם המשתמש לאימות כשמתחברים דרך שרת proxy שנדרש לכך. לא רלוונטי String לא
QueryDialect ניב ה-SQL להרצת השאילתה. משתמשים ב-SQL ל-GoogleSQL (מומלץ מאוד) וב-BIG_QUERY ל-SQL מדור קודם. SQL String לא
QueryProperties מאפייני חיבור REST שמשמשים להתאמה אישית של התנהגות השאילתה. לא רלוונטי ‫Map<String, String> לא
RequestGoogleDriveScope מוסיף היקף גישה לקריאה בלבד ב-Drive לחיבור כשהערך הוא 1. 0 מספר שלם לא
RetryInitialDelay ההשהיה (בשניות) לפני הניסיון החוזר הראשון. 0 ארוכה לא
RetryMaxDelay הגדרת המגבלה המקסימלית (בשניות) של השהיית הניסיון החוזר. 0 ארוכה לא
ServiceAccountImpersonationChain רשימה מופרדת בפסיקים של כתובות אימייל של חשבונות שירות בשרשרת ההתחזות. לא רלוונטי String לא
ServiceAccountImpersonationEmail כתובת האימייל בחשבון השירות שרוצים להתחזות אליו. לא רלוונטי String לא
ServiceAccountImpersonationScopes רשימה של היקפי הרשאות OAuth2 שמופרדים באמצעות פסיקים, לשימוש עם החשבון המתחזה. https://www.googleapis.com/auth/bigquery String לא
ServiceAccountImpersonationTokenLifetime משך החיים של האסימון של החשבון שהתבצעה אליו התחזות (בשניות). 3600 מספר שלם לא
SSLTrustStore הנתיב המלא אל Java TrustStore שמכיל אישורי רשות אישורים (CA) מהימנים. מנהל ההתקן משתמש במאגר האישורים הזה כדי לאמת את הזהות של השרת במהלך לחיצת היד ב-SSL/TLS. לא רלוונטי String לא
SSLTrustStoreProvider ספק Java Cryptography Extension‏ (JCE) שמשמש למאפיין SSLTrustStore. לא רלוונטי String לא
SSLTrustStorePwd הסיסמה ל-Java TrustStore שצוינה במאפיין SSLTrustStore. לא רלוונטי String רק אם מאגר האישורים של Java מוגן בסיסמה
SSLTrustStoreType הפורמט של קובץ מאגר האישורים שצוין במאפיין SSLTrustStore (למשל JKS,‏ PKCS12 או ROTKS). לא רלוונטי String לא
SWA_ActivationRowCount הסף של executeBatch insert שורות, שאם הוא נחצה, גורם למחבר לעבור ל-Storage Write API ‏ (gRPC). 3 מספר שלם לא
SWA_AppendRowCount הגודל של זרם הכתיבה. 1000 מספר שלם לא
Timeout משך הזמן בשניות שבו המחבר מנסה שוב לבצע קריאה ל-API שנכשלה לפני שחלף הזמן הקצוב לתפוגה. 0 ארוכה לא
UniverseDomain הדומיין ברמה העליונה שמשויך ל Google Cloud משאבים של הארגון. googleapis.com String לא
UnsupportedHTAPIFallback ההגדרה קובעת אם המחבר יחזור ל-REST API (כשהערך הוא TRUE) או יחזיר שגיאה (כשהערך הוא FALSE). TRUE בוליאני לא
UseGlobalOpenTelemetry ההגדרה קובעת אם מנהל ההתקן משתמש ב-GlobalOpenTelemetry.get() לצורך מדידה. מידע נוסף זמין במאמר בנושא OpenTelemetry. FALSE בוליאני לא
UseQueryCache הפעלת שמירת שאילתות במטמון. TRUE בוליאני לא

הרצת שאילתות באמצעות הדרייבר

אחרי שהאפליקציה שלכם ב-Java מחוברת ל-BigQuery דרך מנהל ההתקן JDBC, אתם יכולים להריץ שאילתות בסביבת הפיתוח שלכם דרך תהליך JDBC רגיל. כל המכסות והמגבלות של BigQuery חלות.

מיפוי סוגי נתונים

כשמריצים שאילתות דרך מנהל ההתקן של JDBC ל-BigQuery, מתבצע מיפוי של סוגי הנתונים הבאים:

סוג GoogleSQL סוג Java
ARRAY Array
BIGNUMERIC BigDecimal
BOOL Boolean
BYTES byte[]
DATE Date
DATETIME String
FLOAT64 Double
GEOGRAPHY String
INT64 Long
INTERVAL String
JSON String
NUMERIC BigDecimal
STRING String
STRUCT Struct
TIME Time
TIMESTAMP Timestamp

דוגמאות

בקטעים הבאים מופיעות דוגמאות לשימוש בתכונות של BigQuery באמצעות מנהל ההתקן JDBC ל-BigQuery.

פרמטרים תלויי מיקום

בדוגמה הבאה מריצים שאילתה עם פרמטר תלוי מיקום:

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

רשומות בתוך רשומות ורשומות חוזרות

בדוגמה הבאה מוצגת שאילתה של רשומת הבסיס של נתוני Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

הדרייבר מחזיר את רשומת הבסיס כאובייקט struct או כייצוג מחרוזת של אובייקט JSON. התוצאה אמורה להיראות כך:

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

בדוגמה הבאה מוצגת שאילתה לגבי רכיבי המשנה של אובייקט Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

הדוגמה הבאה מציגה שאילתה של מערך רגיל של נתונים חוזרים, ואז בודקת את התוצאה:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

בדוגמה הבאה מבוצעת שאילתה על Struct מערך של נתונים חוזרים, ואז מתבצעת בדיקה של התוצאה:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

הוספה בכמות גדולה

בדוגמה הבאה מבוצעת פעולת הוספה בכמות גדולה באמצעות השיטה executeBatch.

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

רישום ביומן

כדי לפתור בעיות במנהל ההתקן של JDBC ל-BigQuery, אפשר להפעיל רישום ביומן על ידי הגדרת מאפייני חיבור או משתני סביבה. רישום ביומן יכול להשפיע על הביצועים ולתפוס מקום בדיסק, לכן מומלץ להפעיל אותו רק באופן זמני כדי לתעד בעיה.

רמות יומן

המאפיין LogLevel קובע את רמת הפירוט שמתועדת בחבילה java.util.logging:

  • ‫0: OFF (ברירת מחדל)
  • 1: SEVERE
  • 2: ‏WARNING
  • 3: ‏INFO
  • 4: ‏CONFIG
  • 5: ‏FINE
  • 6: ‏FINER
  • 7: ‏FINEST
  • 8: ALL

אנחנו ממליצים על רמה 6 לפתרון בעיות כללי. רמות 7 ו-8 מוגבלות ל-ResultSet פעולות, ומייצרות נפח גדול של יומנים.

הפעלת הרישום ביומן במחרוזת החיבור

כדי להפעיל את הרישום ביומן במחרוזת החיבור, מוסיפים את מאפייני החיבור LogLevel ו-LogPath, לדוגמה:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

הפעלת רישום ביומן באמצעות משתני סביבה

אם כלי הפיתוח לא מאפשר עריכה של מחרוזת החיבור, אפשר גם להגדיר את רמת היומן ונתיב היומן באמצעות משתני הסביבה הבאים לפני שמריצים את האפליקציה:

  • ‫BIGQUERY_JDBC_LOG_LEVEL: רמת היומן (0-8).
  • ‫BIGQUERY_JDBC_LOG_PATH: הספרייה של קובצי היומן.

לדוגמה, בסביבה של Linux או macOS, מריצים את הפקודה הבאה:

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelemetry

מנהל ההתקן של JDBC ל-BigQuery תומך ב-OpenTelemetry‏ (OTel) כדי לספק מעקב ורישום מבוזרים, שמאפשרים לכם לעקוב אחרי הביצועים של האינטראקציות עם מסד הנתונים ולפתור בעיות ביעילות.

פעולות שניתן לעקוב אחריהן

כשהתכונה OpenTelemetry מופעלת, מנהל ההתקן יוצר טווחים לפעולות הבאות:

  • ביצוע השאילתה: נוצרים טווחים עבור BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) ועבור BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
  • פעולות מטא-נתונים: נוצרים טווחים לשיטות ספציפיות (DatabaseMetaData, getCatalogs(), getSchemas(), getTables(), getColumns()).
  • חלוקה לעמודים: אחזור אסינכרוני של דפים נוספים של תוצאות (בשימוש בנתיב API בארכיטקטורת REST) מתועד ומקושר סיבתית לטווח הביצוע של השאילתה המקורית באמצעות OpenTelemetry Span Links. נוצר span בשם BigQueryStatement.pagination עבור הפעולות האלה.
  • העברת הקשר: מנהל ההתקן של JDBC מעביר את ההקשר הפעיל אל google-cloud-bigquery SDK הבסיסי. כתוצאה מכך, טווחי זמן שנוצרו על ידי ה-SDK (כמו קריאות HTTP RPC) מופיעים אוטומטית כצאצאים של טווחי הזמן של JDBC, וכך מספקים היררכיית מעקב מלאה מקצה לקצה.

מצבי הגדרה

אפשר להגדיר את OpenTelemetry במנהל התקן JDBC באחד מהמצבים הבאים, בהתאם לארכיטקטורה ולדרישות של האפליקציה.

טלמטריה שמנוהלת על ידי האפליקציה

אם האפליקציה שלכם כבר משתמשת ב-OpenTelemetry, אתם יכולים להחדיר את מופע OpenTelemetry למנהל ההתקן של JDBC כדי לוודא שהטלמטריה של מנהל ההתקן מתואמת לטלמטריה של האפליקציה.

כדי לעשות את זה, משתמשים ב-BigQueryDataSource API:

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

תמיכה גלובלית ב-OpenTelemetry

אם הפעלתם את OpenTelemetry באופן גלובלי באפליקציה (לדוגמה, באמצעות OpenTelemetry Java Agent או על ידי קריאה לפונקציה GlobalOpenTelemetry.set()), אתם יכולים להגדיר את הדרייבר כך שישתמש במופע הגלובלי הזה.

כדי להפעיל את המופע הגלובלי, מגדירים את מאפיין החיבור UseGlobalOpenTelemetry לערך TRUE.

טלמטריה Google Cloud ללא הגדרה

אם אתם מריצים את Google Cloud ואתם רוצים להגדיר את המערכת במהירות, אתם יכולים להפעיל ייצוא אוטומטי של עקבות ויומנים אל Google Cloud observability (Trace ו-Logging).

כדי להפעיל את הייצוא הזה, צריך להגדיר את מאפייני החיבור הבאים בכתובת ה-URL של JDBC:

  • EnableGcpTraceExporter=true
  • EnableGcpLogExporter=true

לדוגמה, כתובת URL לחיבור:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

מאפייני חיבור של OpenTelemetry

המאפיינים הבאים של החיבור נתמכים ב-OpenTelemetry. תיאורים מפורטים וערכי ברירת מחדל זמינים במאמר בנושא מאפייני חיבור.

  • EnableGcpLogExporter
  • EnableGcpTraceExporter
  • GcpTelemetryCredentials
  • GcpTelemetryProjectId
  • UseGlobalOpenTelemetry

שיקולים חשובים

כשפורסים שילוב של OpenTelemetry, חשוב להביא בחשבון את הנקודות הבאות לגבי התנהגות הרישום ביומן, האימות והתמחור.

אינטראקציה עם LogLevel

נכס הקישור הקיים LogLevel משמש כשומר סף ראשי לצורך רישום ביומן.

  • אם מוגדר LogLevel=0 (OFF), לא נוצרות רשומות ביומן. לכן, לא מתבצע ייצוא של יומנים באמצעות OpenTelemetry או אל Logging, גם אם EnableGcpLogExporter=true.
  • כדי להפעיל רישום ביומן של OTel, צריך לוודא שהערך של LogLevel גדול מ-0 (לדוגמה, 5 ליומנים מפורטים).

אימות לטלמטריה

ייצוא טלמטריה (גם מעקב וגם רישום ביומן) עםGoogle Cloud fallback אוטומטי תומך גם ב-Application Default Credentials ‏(ADC) וגם בפרטי כניסה מפורשים לחשבון שירות שסופקו באמצעות GcpTelemetryCredentials.

אם מציינים את GcpTelemetryProjectId או את GcpTelemetryCredentials, גם היומנים וגם העקבות נשלחים לאותו פרויקט יעד שצוין באמצעות אותם פרטי כניסה שהוגדרו.

ממשקי API והרשאות IAM נדרשים

כדי לכתוב נתוני טלמטריה אל Google Cloud observability, מבצעים את ההגדרה הבאה בפרויקט Google Cloud היעד:

  1. מפעילים את ממשקי ה-API:
    • מפעילים את Cloud Trace API ‏ (cloudtrace.googleapis.com).
    • מפעילים את Cloud Logging API ‏ (logging.googleapis.com).
  2. הקצאת תפקידי IAM:
    • לייצוא נתוני מעקב: מקצים לחשבון המשתמש או לחשבון השירות את התפקיד Trace Agent (סוכן מעקב) ‏(roles/cloudtrace.agent).
    • לייצוא יומנים: צריך לתת לישות המורשית או לחשבון השירות את התפקיד 'בעל הרשאת כתיבה ביומן' (roles/logging.logWriter).

תמחור וחיוב

כשמשתמשים בטלמטריה Google Cloud ללא הגדרה (EnableGcpTraceExporter=true או EnableGcpLogExporter=true), נתוני הטלמטריה נשלחים ל-Trace ול-Logging. יכול להיות שיהיו חיובים על השירותים האלה בהתאם לנפח הנתונים שמועברים אליהם. מידע נוסף זמין במאמר בנושא Google Cloud Observability.

מדדים

השילוב הזה לא תומך במדדים של OpenTelemetry.

הצללה של תלות

כדי למנוע התנגשויות בנתיב המחלקה עם האפליקציה, מנהל ההתקן מסתיר את יחסי התלות של OpenTelemetry SDK ושל רכיב הייצוא. ‫OpenTelemetry API לא מוצלל כדי לאפשר פעולה הדדית עם SDK שסופק על ידי האפליקציה.

רישום ביומן ומתאם בין עקבות

כשהאפשרות OpenTelemetry מופעלת, מנהל ההתקן מקשר באופן אוטומטי בין יומנים לבין עקבות:

  • db.connection_id: מצורף כמאפיין של יחידה לוגית למעקב לכל היחידות הלוגיות למעקב של JDBC.
  • ‫jdbc.connection_id: משמש כמפתח של נתוני Baggage ומצורף כתווית לכל רשומות היומן שמופקות על ידי הדרייבר ל-Logging.
  • מזהה מעקב ומזהה יחידה לוגית למעקב: יומנים שנוצרים במסגרת של הרצת שאילתה כוללים באופן אוטומטי את trace_id וspan_id הפעילים.

תמחור

אפשר להוריד את מנהל ההתקן JDBC ל-BigQuery ללא עלות. עם זאת, כשמשתמשים בדרייבר, חלים תעריפי BigQuery הרגילים.

המאמרים הבאים