開発者向けドキュメント > 開発者向け学習 > Python API client user guide > データ > データ接続の構築

データ接続の構築¶

データベースは、貴重なビジネスデータを保持するために広く利用されているツールです。さまざまなエンタープライズデータベースとの連携を可能にするため、DataRobotにはデータベース接続設定のためのセルフサービスJDBC製品が用意されています。設定した後は、運用データベースからデータを読み取ってモデル構築と予測に使用することができます。 This allows you to quickly train and retrain models on that data, and avoids the unnecessary step of exporting data from your enterprise database to a CSV for ingest to DataRobot. With access to more diverse data, you can build more accurate models.

データベース接続の用語¶

Database connection configuration uses the following terminology:

Data store: A configured connection to a database. It has a name, a specified driver, and a JDBC URL. You can register data stores with DataRobot for ease of re-use. A data store has one connector but can have many data sources.
Data source: A configured connection to the backing data store (the location of data within a given endpoint). A data source specifies, via a SQL query or a selected table and schema data, which data to extract from the data store to use for modeling or predictions. A data source has one data store and one connector but can have many datasets.
Data driver: The software that allows the application to interact with a database; each data store is associated with either a driver or a connector (created by the administrator). The driver configuration saves the storage location in the application of the JAR file and any additional dependency files associated with the driver.
Connector: Similarly to data drivers, a connector allows the application to interact with a database; each data store is associated with either a driver or a connector (created by the administrator). The connector configuration saves the storage location in the application of the JAR file and any additional dependency files associated with the connector.
Dataset: Data, a file or the content of a data source, at a particular point in time. A data source can produce multiple datasets; a dataset has exactly one data source.

Review the workflow to set up projects or prediction datasets below.

管理者は、特定のデータベースにアクセスするためにdatarobot.DataDriverを設定します。特定のドライバーについては、この設定はシステム全体に対して一度だけ行われ、その結果として生成されたドライバーはすべてのユーザーによって使用されます。
ユーザーは、そのドライバーを使用する特定のデータベースへのインターフェイスを表すdatarobot.DataStoreを作成します。
ユーザーは、データストアから抽出する特定のデータセットを表すdatarobot.DataSourceを作成します。
Users create projects and prediction datasets from a data source.

ユーザーはデータストアとデータソースを管理できます。一方、管理者はドライバーの既存のインスタンスを一覧表示、取得、更新、および削除することによってドライバーを管理できます。

ドライバーの作成¶

ドライバーを作成するには、管理者は以下を指定する必要があります。

class_name：タイプがJDBCの場合は、ドライバーのJavaクラス名。それ以外の場合はNone。
canonical_name：APIおよびGUIに表示するわかりやすい名前または結果として生成されたドライバー。
files：タイプがJDBCの場合は、ドライバーを含むローカルファイルのリスト。それ以外の場合は省略。
typ：ドライバーのタイプを示す列挙型。デフォルトはdr.enums.DataDriverTypes.JDBCですが、dr.enums.DataDriverTypes.DR_DATABASE_V1にすることもできます。
database_driver：JDBC以外で使用するネイティブデータベースのタイプ。たとえば、dr.enums.DrDatabaseV1Types.BIGQUERY。

>>> import datarobot as dr
>>> driver = dr.DataDriver.create(
...     class_name='org.postgresql.Driver',
...     canonical_name='PostgreSQL',
...     files=['/tmp/postgresql-42.2.2.jar']
... )
>>> driver
DataDriver('PostgreSQL')

JDBC以外のドライバーを作成するには、以下のコードを使用します。

driver = dr.DataDriver.create(None, "BigQuery Native", typ=dr.enums.DataDriverTypes.DR_DATABASE_V1, database_driver=dr.enums.DrDatabaseV1Types.BIGQUERY)

To retrieve information about existing drivers, such as the driver ID for data store creation, you can use dr.DataDriver.list().

データストアの作成¶

管理者がドライバーを作成すると、すべてのユーザーがそのドライバーを使用してDataStoreを作成できます。データストアは、JDBCデータベースまたはJDBC以外のデータベースを表します。作成時には、以下を指定する必要があります。

type：タイプはdr.enums.DataStoreTypes.DR_DATABASE_V1またはdr.enums.DataStoreTypes.JDBCである必要があります。
canonical_name：APIおよびGUIに表示するデータストアのわかりやすい名前。
driver_id：データベースへの接続に使用するドライバーのID。
jdbc_url：タイプがJDBCの場合にデータベースタイプ、サーバーアドレス、ポート、データベース名などのデータベース接続設定を指定する完全なURL。
フィールド：タイプがdr.enums.DataStoreTypes.DR_DATABASE_V1の場合に使用されるフィールド。辞書エントリーのリスト。各エントリーにはID、名前、値のフィールドが含まれます。

備考

Pythonクライアントを使用する場合、データストアはドライバーを用いてのみ作成できます。 Drivers and connectors are not interchangeable for this method. コネクターを用いてデータストアを作成するには、代わりにREST APIを使用します。

>>> import datarobot as dr
>>> data_store = dr.DataStore.create(
...     data_store_type='jdbc',
...     canonical_name='Demo DB',
...     driver_id='5a6af02eb15372000117c040',
...     jdbc_url='jdbc:postgresql://my.db.address.org:5432/perftest'
... )
>>> data_store
DataStore('Demo DB')
>>> data_store.test(username='username', password='password')
{'message': 'Connection successful'}

代わりにフィールドを使用して、JDBC以外のデータストアを作成できます。

>>> fields = [
...     {
...         "id": "bq.project_id",
...         "name": "Project Id",
...         "value": "mldata-358421",
...     }
... ]
>>> data_store = dr.DataStore.create(
...     data_store_type=dr.enums.DataStoreTypes.DR_DATABASE_V1,
...     canonical_name='BigQuery Native Connection',
...     driver_id=driver_id,
...     fields=fields
... )

データストアの表示¶

すでに存在するデータストアを表示するには、以下のコードを使用します。ただし、dr.DataStore.list()を呼び出しても、すべてのデータストアがデフォルトで表示されるわけではないことに注意してください。デフォルトではJDBC接続のみが表示されるため、typ=dr.enums.DataStoreListTypes.ALL引数を明示的に渡す必要があります。

すべてのJDBCデータストアを一覧表示（デフォルト）：

data_stores = dr.DataStore.list()

print(f"Found {len(data_stores)} DataStore(s):")
for ds in data_stores:
    print(f"  - {ds.canonical_name} (ID: {ds.id}, Type: {ds.data_store_type})")

すべてのデータストアを一覧表示：

all_stores = dr.DataStore.list(typ=dr.enums.DataStoreListTypes.ALL)

データストアへのクエリー¶

datarobot.DataStoreを作成すると、そのデータストアに対して直接SQLを実行できます。結果を返すクエリーにはpreview_query()を、UPDATE、INSERT、DELETEなどの更新文にはexecute_update()を使用してください。

備考

この機能は、構造化データをサポートするデータストア、つまりSQLクエリーを実行できるデータストアでのみ利用可能です。

preview_queryを使用すると、SQL文を実行して結果のプレビューを取得できます。

>>> import datarobot as dr
>>> data_store = dr.DataStore.get('5a8ac90b09a57a0001be306e')
>>> preview = data_store.preview_query(
...     "SELECT * FROM my_catalog.my_schema.my_table WHERE name LIKE ?",
...     credential_id='9963d544d5ce3se783r12190',
...     max_rows=10,
...     bind_parameters=['%Doe%'],
... )
>>> preview.columns
['id', 'name', 'email']
>>> preview.records
[
    {'id': 1, 'name': 'John Doe', 'email': 'john.doe@example.com'},
    {'id': 2, 'name': 'Jane Doe', 'email': 'jane.doe@example.com'},
]

bind_parameters引数は、値を順にSQL文内の?プレースホルダーにバインドします。

データストアに対して更新文を実行するには、execute_updateを使用します。

>>> data_store.execute_update(
...     "UPDATE my_table SET name = ? WHERE id = ?",
...     credential_id='9963d544d5ce3se783r12190',
...     bind_parameters=['John', 1],
... )
'OK'

execute_updateは、成功した場合にサーバーから'OK'というメッセージを返します。プログラムで結果を確認するには、DataStore.is_execute_update_success()を使用します。

>>> message = data_store.execute_update(
...     "UPDATE my_table SET name = 'John Doe' WHERE id = 1"
... )
>>> dr.DataStore.is_execute_update_success(message)
True

JDBC接続を使用したクエリー¶

datarobot.DataStoreを事前に作成することなく、JDBC URLに対して直接SQLを実行することもできます。 JDBC URLと資格情報をdatarobot.JdbcPreviewに直接指定すると、DataRobotはリクエストが実行されている間、データベースに接続します。結果を返すクエリーにはJdbcPreview.preview()を使用し、UPDATE、INSERT、DELETEなどの更新文にはJdbcPreview.execute_update()を使用します。

preview()を使用すると、JDBC URLに対してSQL文を実行し、結果のJdbcPreviewDataプレビューを返すことができます。

>>> import datarobot as dr
>>> preview = dr.JdbcPreview.preview(
...     jdbc_url='jdbc:postgresql://localhost:5432/mydb',
...     sql='SELECT id, name, email FROM public.users WHERE age = ?',
...     max_rows=5,
...     parameters={'user': 'dbuser', 'password': 'secret'},
...     bind_parameters=[25],
... )
>>> preview.columns
['id', 'name', 'email']
>>> len(preview.records)
5
>>> preview.df['name'].head(5)
0    John Doe
1    Jane Doe
2    Alice Smith
3    Bob Johnson
4    Carol White
Name: name, dtype: object

parameters引数は、接続の資格情報やオプション（user、password、ssl、timeout など）を、JDBC URLに埋め込むのではなく、キーと値のペアとして渡します。

execute_update()を使用すると、JDBC URLに対して更新文を実行できます。

>>> dr.JdbcPreview.execute_update(
...     jdbc_url='jdbc:postgresql://localhost:5432/mydb',
...     sql='INSERT INTO my_table (id, name) VALUES (?, ?)',
...     parameters={'user': 'dbuser', 'password': 'secret'},
...     bind_parameters=[1, 'John'],
... )
'OK'

`QueryEngine`を使用したクエリー¶

QueryEngineはdatarobotパッケージのアドオンであり、上記のクエリーメソッドを馴染みのある SQLAlchemyの構文でラップしています。これにより、位置指定型の?プレースホルダーや生のSQL文字列の代わりに、名前付きパラメーターバインディング（:name）やSQLAlchemyの構成要素（select()やinsert()など）を使用できるようになります。

これを使用するには、datarobotのquery-engineパッケージアドオンをインストールしてください。

pip install 'datarobot[query-engine]'

JDBC接続（from_jdbc_connection）または既存のデータストアのID（from_data_store）からQueryEngineを作成します。

>>> from datarobot.query_engine import QueryEngine
>>> engine = QueryEngine.from_jdbc_connection(
...     jdbc_url='jdbc:postgresql://localhost:5432/mydb',
...     jdbc_params={'user': 'dbuser', 'password': 'secret'},
... )

>>> engine = QueryEngine.from_data_store(
...     data_store_id='5a8ac90b07a57a0001be501e',
...     credential_id='9963d544d5ce3se783r12190',
... )

execute()を使用し、名前付きパラメーターを指定して文を実行します。

>>> results = engine.execute(
...     "SELECT * FROM users WHERE name = :name",
...     params={"name": "John Doe"},
... )
>>> results.all()
[(1, "John Doe")]

生のSQL文字列の代わりに既存のSQLAlchemyの構成要素を渡すこともでき、同様の方法でパラメーターをバインドできます。

>>> from sqlalchemy import select, bindparam, column, table
>>> USER_TABLE = table("users", column("name"), column("status"))
>>> results = engine.execute(
...     select(USER_TABLE)
...         .where(USER_TABLE.c.name == "John Doe")
...         .where(USER_TABLE.c.status == bindparam("status")),
...     params={"status": "active"},
... )
>>> results.all()
[("John Doe", "active")]

execute() は、文の最初のキーワードに基づいて、その文が行を返すかどうかを推測するために、ベストエフォート型のヒューリスティックを使用します。SELECT、WITH、SHOWなどのクエリーキーワードで始まる文は結果として取得されますが、INSERT、UPDATE、DELETEなどの文は副作用を伴うものとみなされ、何も返さないものとされます。

備考

execute()が文の行を返すはずなのに返さない場合、QueryEngineが、その文が結果を返さないと誤って判断した可能性があります。 mode=QueryMode.QUERYを指定することで、execute()に結果の取得を強制することができます。

>>> from datarobot.query_engine import QueryMode
>>> results = engine.execute(
...     "UPDATE users SET status = 'active' WHERE name = 'John Doe' RETURNING id, name, status",
...     mode=QueryMode.QUERY,
... )
>>> results.all()
[(1, "John Doe", "active")]

リストやタプルに対するバインドされたパラメーターの展開など、その他の例については、QueryEngineのAPIリファレンスを参照してください。

データソースの作成¶

Once you have a data store, you can query datasets via the data source. データソースを作成するときは、まずデータストアのIDとクエリーからdatarobot.DataSourceParametersオブジェクトを作成します。次に、以下の内容でデータソースを作成します。

type：タイプはdr.enums.DataStoreTypes.DR_DATABASE_V1またはdr.enums.DataStoreTypes.JDBCである必要があります。
canonical_name：APIおよびGUIに表示するわかりやすい名前。
params：DataSourceParametersオブジェクト。

>>> import datarobot as dr
>>> params = dr.DataSourceParameters(
...     data_store_id='5a8ac90b07a57a0001be501e',
...     query='SELECT * FROM airlines10mb WHERE "Year" >= 1995;'
... )
>>> data_source = dr.DataSource.create(
...     data_source_type='jdbc',
...     canonical_name='airlines stats after 1995',
...     params=params
... )
>>> data_source
DataSource('airlines stats after 1995')

フィールドを使用して、JDBC以外のデータストアを作成できます。

>>> params = dr.DataSourceParameters(
...     data_store_id=data_store_id,
...     catalog=catalog,
...     schema=schema,
...     table=table,
... )
>>> data_source = dr.DataSource.create(
...     data_source_type=dr.enums.DataStoreTypes.DR_DATABASE_V1,
...     canonical_name='BigQuery Data Source',
...     driver_id=driver_id,
...     params=params
... )

Create projects¶

You can create new projects from a data source, demonstrated below.

>>> import datarobot as dr
>>> project = dr.Project.create_from_data_source(
...     data_source_id='5ae6eee9962d740dd7b86886',
...     username='username',
...     password='password'
... )

As of v3.0 of the Python API client, you can alternatively pass in the credential_id of an existing Dataset.Credential object.

>>> import datarobot as dr
>>> project = dr.Project.create_from_data_source(
...     data_source_id='5ae6eee9962d740dd7b86886',
...     credential_id='9963d544d5ce3se783r12190'
... )

あるいは、CredentialDataSchemaに準拠したcredential_dataを渡します。

>>> import datarobot as dr
>>> s3_credential_data = {"credentialType": "s3", "awsAccessKeyId": "key123", "awsSecretAccessKey": "secret123"}
>>> project = dr.Project.create_from_data_source(
...     data_source_id='5ae6eee9962d740dd7b86886',
...     credential_data=s3_credential_data
... )

Create prediction datasets¶

Given a data source, new prediction datasets can be created for any project.

>>> import datarobot as dr
>>> project = dr.Project.get('5ae6f296962d740dd7b86887')
>>> prediction_dataset = project.upload_dataset_from_data_source(
...     data_source_id='5ae6eee9962d740dd7b86886',
...     username='username',
...     password='password'
... )