You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can use Pinecone Datasets to load our public datasets or with your own dataset.
11
+
You can use Pinecone Datasets to load our public datasets or with your own datasets. Datasets library can be used in 2 main ways: ad-hoc loading of datasets from a path or as a catalog loader for datasets.
12
12
13
-
### Loading Pinecone Public Datasets
13
+
### Loading Pinecone Public Datasets (catalog)
14
+
15
+
Pinecone hosts a public datasets catalog, you can load a dataset by name using `list_datasets` and `load_dataset` functions. This will use the default catalog endpoint (currently GCS) to list and load datasets.
14
16
15
17
```python
16
18
from pinecone_datasets import list_datasets, load_dataset
- note: blob is a dict that can contain any data, it is not returned when iterating over the dataset and is inteded to be used for storing additional data that is not part of the dataset schema. however, it is sometime useful to store additional data in the dataset, for example, a document text. In future version this may become a first class citizen in the dataset schema.
61
+
-`queries` directory contains parquet files with the following schema:
- note: filter is a dict that contain pinecone filters, for more information see [here](https://docs.pinecone.io/docs/metadata-filtering)
65
+
66
+
in addition, a metadata file is expected to be in the dataset directory, for example: `s3://my-bucket/my-dataset/metadata.json`
67
+
68
+
```python
69
+
from pinecone_datasets.catalog import DatasetMetadata
47
70
71
+
meta = DatasetMetadata(
72
+
name="test_dataset",
73
+
created_at="2023-02-17 14:17:01.481785",
74
+
documents=2,
75
+
queries=2,
76
+
source="manual",
77
+
bucket="LOCAL",
78
+
task="unittests",
79
+
dense_model={"name": "bert", "dimension": 3},
80
+
sparse_model={"name": "bm25"},
81
+
)
48
82
```
49
83
50
-
### upserting to Index
84
+
full metadata schema can be found in `pinecone_datasets.catalog.DatasetMetadata.schema`
85
+
86
+
### Loading your own dataset from catalog
87
+
88
+
To set you own catalog endpoint, set the environment variable `DATASETS_CATALOG_BASEPATH` to your bucket. Note that pinecone uses the default authentication method for the storage type (gcsfs for GCS and s3fs for S3).
for batch in dataset.iter_documents(batch_size=100):
66
-
index.upsert(vectors=batch)
106
+
You can load your own dataset from a local path or a remote path (GCS or S3). Note that pinecone uses the default authentication method for the storage type (gcsfs for GCS and s3fs for S3).
Pinecone Datasets enables you to load a dataset from a pandas dataframe. This is useful for loading a dataset from a local file and saving it to a remote storage.
117
+
The minimal required data is a documents dataset, and the minimal required columns are `id` and `values`. The `id` column is a unique identifier for the document, and the `values` column is a list of floats representing the document vector.
76
118
77
-
### Working with your own dataset storage
119
+
```python
120
+
import pandas as pd
78
121
79
-
Datasets is using Pinecone's public datasets bucket on GCS, you can use your own bucket by setting the `DATASETS_CATALOG_BASEPATH` environment variable.
this will change the default endpoint to your bucket, and upon calling `list_datasets` or `load_dataset` it will scan your bucket and list all datasets.
127
+
Please check the documentation for more information on the expected dataframe schema. There's also a column mapping variable that can be used to map the dataframe columns to the expected schema.
86
128
87
-
Note that you can also use `s3://` as a prefix to your bucket.
88
129
89
-
### Authenication to your own bucket
130
+
##Usage - Accessing data
90
131
91
-
For now, Pinecone Datastes supports only GCS and S3 buckets, and with default authentication as provided by the fsspec implementation, respectively: `gcsfs` and `s3fs`.
132
+
Pinecone Datasets is build on top of pandas. This means that you can use all the pandas API to access the data. In addition, we provide some helper functions to access the data in a more convenient way.
92
133
93
-
### Using aws key/secret authentication methods
134
+
### Accessing documents and queries dataframes
94
135
95
-
first, to set a new endpoint, set the environment variable `PINECONE_DATASETS_ENDPOINT` to your bucket.
136
+
accessing the documents and queries dataframes is done using the `documents` and `queries` properties. These properties are lazy and will only load the data when accessed.
then, you can use the `key` and `secret` parameters to pass your credentials to the `list_datasets` and `load_dataset` functions.
102
144
103
-
```python
104
-
st = list_datasets(
105
-
key=os.environ.get("S3_ACCESS_KEY"),
106
-
secret=os.environ.get("S3_SECRET"),
107
-
)
108
-
109
-
ds = load_dataset(
110
-
"test_dataset",
111
-
key=os.environ.get("S3_ACCESS_KEY"),
112
-
secret=os.environ.get("S3_SECRET"),
113
-
)
114
-
```
145
+
## Usage - Iterating
115
146
116
-
## For developers
147
+
One of the main use cases for Pinecone Datasets is iterating over a dataset. This is useful for upserting a dataset to an index, or for benchmarking. It is also useful for iterating over large datasets - as of today, datasets are not yet lazy, however we are working on it.
117
148
118
-
This project is using poetry for dependency managemet. supported python version are 3.8+. To start developing, on project root directory run:
119
149
120
-
```bash
121
-
poetry install --with dev
122
-
```
150
+
```python
123
151
124
-
To run test locally run
152
+
# List Iterator, where every list of size N Dicts with ("id", "values", "sparse_values", "metadata")
153
+
dataset.iter_documents(batch_size=n)
154
+
155
+
# Dict Iterator, where every dict has ("vector", "sparse_vector", "filter", "top_k")
156
+
dataset.iter_queries()
125
157
126
-
```bash
127
-
poetry run pytest --cov pinecone_datasets
128
158
```
129
159
130
-
To create a pinecone-public dataset you may need to generate a dataset metadata. For example:
160
+
### The 'blob' column
161
+
162
+
Pinecone dataset ship with a blob column which is inteneded to be used for storing additional data that is not part of the dataset schema. however, it is sometime useful to store additional data in the dataset, for example, a document text. We added a utility function to move data from the blob column to the metadata column. This is useful for example when upserting a dataset to an index and want to use the metadata to store text data.
131
163
132
164
```python
133
-
from pinecone_datasets.catalogimportDatasetMetadata
165
+
from pinecone_datasets importimport_documents_keys_from_blob_to_metadata
When upserting a Dataset to an Index, only the document data will be upserted to the index. The queries data will be ignored.
153
174
154
-
in order to list a dataset you can save dataset metadata (NOTE: write permission to loacaion is needed)
175
+
TODO: add example for API Key adn Environment Variables
155
176
156
177
```python
157
-
dataset = Dataset("non-listed-dataset")
158
-
dataset._save_metadata(meta)
159
-
```
178
+
ds = load_dataset("dataset_name")
160
179
161
-
### Uploading and listing a dataset.
180
+
# If index exists
181
+
ds.to_index("index_name")
162
182
163
-
pinecone datasets can load dataset from every storage where it has access (using the default access: s3, gcs or local permissions)
183
+
# If index does not exist use create_index=True, this will create the index with the default pinecone settings and dimension from the dataset metadata.
184
+
ds.to_index("index_name", create_index=True)
164
185
165
-
we expect data to be uploaded to the following directory structure:
186
+
```
166
187
167
-
├── base_path # path to where all datasets
168
-
│ ├── dataset_id # name of dataset
169
-
│ │ ├── metadata.json # dataset metadata (optional, only for listed)
170
-
│ │ ├── documents # datasets documents
171
-
│ │ │ ├── file1.parquet
172
-
│ │ │ └── file2.parquet
173
-
│ │ ├── queries # dataset queries
174
-
│ │ │ ├── file1.parquet
175
-
│ │ │ └── file2.parquet
176
-
└── ...
188
+
the `to_index` function also accepts additional parameters
177
189
178
-
a listed dataset is a dataset that is loaded and listed using `load_dataset` and `list_dataset`
179
-
pinecone datasets will scan storage and will list every dataset with metadata file, for example: `s3://my-bucket/my-dataset/metadata.json`
190
+
*`batch_size` and `concurrency` - for controlling the upserting process
191
+
*`kwargs` - for passing additional parameters to the index creation process
180
192
181
-
### Accessing a non-listed dataset
182
193
183
-
to access a non listed dataset you can directly load it via:
194
+
## For developers
184
195
185
-
```python
186
-
from pinecone_datasets import Dataset
196
+
This project is using poetry for dependency managemet. supported python version are 3.8+. To start developing, on project root directory run:
0 commit comments