Initial version of youcat documentaion.#212
Conversation
shinybrar
left a comment
shinybrar
left a comment
There was a problem hiding this comment.
- There is no Python API workflow included. You need to add better information for both CLI / Python API for installation, discovery, sync/async query, and certificate-authentication examples. PyVO is the best fit: it explicitly supports YouCat-style create_table, load_table, create_index, and remove_table, though not permissions. PyVO TAP documentation
- Also mention that for opensource tables, no auth is needed.
|
|
||
| Run a few queries: | ||
| ```bash | ||
| cadc-tap query <tablename> 'query' |
There was a problem hiding this comment.
cadc-tap query <tablename> 'query' is invalid; the CLI accepts one ADQL query positional.
This violates the repo requirement that documentation match implemented behavior. cadctap parser
| While table creation is done only using VOTable format, table | ||
| loading is done using FITS, .csv (comma separated values) and | ||
| .tsv (tab separated values). Convert your table to one of those | ||
| formats. | ||
|
|
||
| You should probably break the table up into smaller chunks of about | ||
| 10000 rows. Smaller than that, the overhead of each call to the service | ||
| will slow things down. Larger than that, the possibility of an error | ||
| taking out a large transfer becomes a challenge. | ||
|
|
||
| Tables are loaded with commands like: | ||
| ```bash | ||
| cadc-tap load <schemaname.tablename> <filename> | ||
| ``` | ||
| e.g.: |
There was a problem hiding this comment.
Incomplete docs, The unqualified load command works only for TSV. CSV requires -f csv; FITS requires -f FITSTable.
There was a problem hiding this comment.
Give separate TSV, CSV, and FITS commands or clearly state that TSV is the default.
| YouCat (=Your Catalog) allows users to upload tables. The tables are then acessible via the [Table Access Protocol (TAP)](https://ws-uv.canfar.net/youcat). YouCat was built after several requests from users who needed to publish a database, but did not have the resources to publish it at their home institutions. Note that YouCat is not optimal for a database use cases requiring frequent updates, modifications or deletions. The permissions can be set so that the database access is restricted to the owner, or shared with a group, or made world-public. | ||
|
|
||
| ## Getting access | ||
| TAP is an IVOA (International Virtual Observatory Alliance) protocol. While loading the table is best done with the CADC python client, querying can be down with the CADC client, but also a large number of other tools, e.g. [topcat](https://www.star.bris.ac.uk/~mbt/topcat/). The TAP handle for youcat is currently: https://ws-uv.canfar.net/youcat | ||
|
|
||
| <!-- TODO --> | ||
| ## Creating a table | ||
|
|
||
| ## Using the TAP API | ||
| ### Step 0. | ||
|
|
||
| <!-- TODO --> | ||
| #### Get write permission for a schema | ||
| If you don't already have a schema, send a short e-mail to support@canfar.net indicating describing the project and size estimates. Turn around is typically 1-2 working days. If there is an existing schema, but you are not the owner, the owner will have to give you write permission. |
There was a problem hiding this comment.
General cleanup of language is needed here, introducing the user to YouCat as a Database as a Service.
| #### Get a certificate | ||
| This is used to authenticate and authorise the puts | ||
| ```bash | ||
| cadc-get-cert --user <CADCusername> |
There was a problem hiding this comment.
This is the CANFAR branding of our tools, all users here can be assumed that they have canfar python project already installed, As a result, this needs to be
canfar login cadcTo require the user to install cadc-tap you have to provide it as python optional, e.g.
pip install canfar[youcat]
This then installs cadc-tap and pyVO as needed. This needs changes to depedency management in the package, via the uv tools,
e.g.
uv add --group youcat cadc-tap
|
|
||
| Run a few queries: | ||
| ```bash | ||
| cadc-tap query <tablename> 'query' |
There was a problem hiding this comment.
Also invalid grammer, use a e.g. a open project, cadc-tap query cfht to provide the user with a real example.
| created to keep track of what was succesfully loaded and load the | ||
| difference. | ||
|
|
||
| ### Step 4: Check the table |
There was a problem hiding this comment.
There is no discovery workflow. Add cadc-tap schema, cadc-tap schema SCHEMA.TABLE, and Python equivalents
| # YouCat | ||
|
|
||
| YouCAT is a CANFAR-branded OpenCADC TAP service for user-owned and managed tables. It is separate from the CANFAR Science Platform. | ||
| YouCat is a database service that lets users create and share tables. It is separate from the CANFAR Science Platform. |
There was a problem hiding this comment.
Explicitly state that YouCat is accessed through TAP using ADQL 2.0—not through PostgreSQL, Python DB-API, or SQLAlchemy connection details.
| ## Permissions and sharing | ||
|
|
||
| <!-- TODO --> | ||
| A newly created table will not generally be readable by others. The general syntax is: |
There was a problem hiding this comment.
The onboarding says a owner must grant write access, but only read-sharing examples are provided. Add schema/table g+w guidance and explain what schema-level versus table-level write access permits.
2 participants
No description provided.