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

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

מגבלות

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

  • הדרייבר ספציפי ל-BigQuery ואי אפשר להשתמש בו עם מוצרים או שירותים אחרים.
  • סוג הנתונים INTERVAL לא נתמך ב-BigQuery Storage Read API.
  • כל המגבלות של שפת טיפול בנתונים (DML) חלות.

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

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

    שיטת אימות פרטי אימות דוגמה נכס חיבור (להגדרה בהמשך)
    חשבון שירות רגיל כתובת האימייל של חשבון השירות bq-jdbc-sa@mytestproject.iam.gserviceaccount.com 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.4.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.4.0</version>
</dependency>

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

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

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.4.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.4.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 Credentials
      • ‫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 נקודת הקצה (endpoint) של הממשק 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 בוליאני לא
EnableTimestampPicos הפונקציה קובעת אם מנהל ההתקן מאחזר ערכים של TIMESTAMP(12) עם דיוק של פיקוסקונד. אם הערך מוגדר כ-TRUE, הערכים של TIMESTAMP(12) מוחזרים כאובייקטים של String בפורמט UTC על ידי הפונקציות getString() ו-getObject(). אם הערך הוא FALSE, TIMESTAMP(12) הערכים נחתכים לדיוק של מיקרו-שנייה עם 6 ספרות. הנכס הזה לא תואם ל-SQL מדור קודם (QueryDialect=BIG_QUERY). 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, מנהל ההתקן מתחיל להשתמש ב-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 TrustStore מוגן בסיסמה
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, חשוב להביא בחשבון את הנקודות הבאות בנוגע להתנהגות הרישום ביומן, האימות, הגדרת ה-proxy והתמחור.

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

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

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

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

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

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

הגדרת שרת Proxy באמצעות OpenTelemetry ורישום ביומן

אם האפליקציה שלכם מתחברת ל-BigQuery דרך שרת proxy, מנהל ההתקן מטפל בניתוב של ה-proxy באופן הבא:

  • ייצוא נתוני מעקב (HTTP). כשמשתמשים בפרוטוקול HTTP שמוגדר כברירת מחדל לייצוא נתוני מעקב של OpenTelemetry‏ (otel.exporter.otlp.protocol=http/protobuf), מנהל ההתקן מנתב באופן אוטומטי את התנועה של ייצוא נתוני המעקב דרך ה-proxy שהוגדר במאפייני החיבור באמצעות ProxyHost ו-ProxyPort.
  • ייצוא יומנים וטלמטריה של gRPC. הכלי האוטומטי Google Cloud לייצוא יומנים (EnableGcpLogExporter=true) והכלים לייצוא OpenTelemetry שמבוססים על gRPC‏ (otel.exporter.otlp.protocol=grpc) משתמשים ב-gRPC, שלא תומך בהגדרת proxy לכל חיבור. כדי לנתב את התנועה של ייצוא יומנים וטלמטריית gRPC דרך שרת proxy, צריך להגדיר את הגדרות לשרת proxy ברמת ה-JVM באמצעות מאפייני המערכת הבאים:

    -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

ממשקי 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: משמש כמפתח מטען ומצורף כתווית לכל רשומות היומן שמופקות על ידי הדרייבר ל-Logging.
  • מזהה מעקב ומזהה יחידה לוגית למעקב: יומנים שנוצרים במסגרת של הרצת שאילתה כוללים באופן אוטומטי את trace_id וspan_id הפעילים.

תמחור

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

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