Overview of the Frames API
Iguazio V3IO Frames ("Frames") is a multi-model open-source data-access library that provides a unified high-performance DataFrame API for working with NoSQL (key-value) and time-series (TSDB) data in the data store of the Iguazio Data Science Platform ("the platform"). This reference describes the library's DataFrame API for Python 3.7. See also the Frames restrictions in the Software Specifications and Restrictions documentation.
In addition to the examples provided in this reference, you can find many examples of using the Frames API in the platform's tutorial Jupyter notebooks.
It's recommended that you begin your development with the
Creating a Frames Service
To use Frames, you first need to create a Frames service:
Servicesdashboard page, select New Servicefrom the top action toolbar.
Basic Settingstab, select V3IO Framesfrom the Service typedrop-down menu. You can optionally edit the service name and description.NoteYou can only create a single shared tenant-wide instance of the Frames service. If the V3IO Framesoption is disabled, this means that the parent tenant already has a Frames service (as indicated in the tooltip for this service type). In this case, cancel the service creation, locate the Frames service in the services table, and verify that it's enabled. Otherwise, proceed to the next step.
Proceed to the
Common Parameterstab and optionally change the default resource configuration; this isn't advisable for new users.
Proceed to the
Custom Parameterstab and select Save Serviceto save your changes.
Apply Changesfrom the top action toolbar of the Servicespage to deploy your changes. When the deployment completes, you should be able to see the Frames service in the services table, as demonstrated in the following image:
To use the Frames API, you need to import the (
import v3io_frames as v3f
Then, you need to create and initialize an instance of the
All Frames client methods receive a
nosqlor kv— a NoSQL backend for working with platform NoSQL (key/value) tables. See Frames NoSQL-Backend API Reference. tsdb— a time-series database (TSDB) backend for working with TSDB tables. See Frames TSDB-Backend API Reference. csv— a CSV backend for working with comma-separated-value (CSV) files. This backend type is used only for testing purposes.
create— creates a new collection.NoteThe createmethod isn't applicable to the NoSQL backend ( nosql | kv), because NoSQL tables in the platform don't need to be created prior to ingestion; when ingesting data into a table that doesn't exist, the table is automatically created. See Working with NoSQL Data. delete— deletes a collection or specific collection items. read— reads data from a collection into pandas DataFrames. write— writes data from pandas DataFrames to a collection. execute— executes a backend-specific command on a collection. Each backend may support multiple commands.
While most methods and commands are supported by all backends, there are differences in the supported parameters and their significance. Therefore, this reference provides separate method documentation for each backend type; see the NoSQL and TDSB backend API references.
When creating a Frames client, you must provide valid platform credentials for accessing the backend data, which Frames will use to identify the identity of the user. This can be done by using any of the following alternative methods (documented in order of precedence):
Provide the authentication credentials in the
Clientconstructor parameters by using either of the following methods:
tokenconstructor parameter to a valid platform access key with the required data-access permissions. You can get the access key from the Access Keyswindow that's available from the dashboard user-profile menu, or by copying the value of the V3IO_ACCESS_KEYenvironment variable in a web-shell or Jupyter Notebook service.
You cannot use both methods concurrently: setting both the
tokenand userand passwordparameters in the same constructor call will produce an error.
- Set the
V3IO_ACCESS_KEYenvironment variable to a valid platform access key with the required data-access permissions.NoteThe platform's Jupyter Notebook service automatically defines the
V3IO_ACCESS_KEYenvironment variable and initializes it to a valid access key for the running user of the service.
- Set the
V3IO_PASSWORDenvironment variables to the username and password of a platform user with the required data-access permissions.Note
- When the client constructor is called with authentication parameters (option #1), the authentication-credentials environment variables (if defined) are ignored.
- Set the