Read completion designs from a file
Completion designs from a CSV or an Excel workbook as named designs, ready for a plan's designs, with what became of each row.
Read completion designs from a file
/completion-designs/readCompletion designs from a CSV or an Excel workbook as named designs, ready for a plan's designs, with what became of each row. Nothing is stored: send the file again to read it again.
Upload
Send the file as multipart/form-data, as curl -F file=@designs.xlsx -F sheet=Designs <origin>/api/v1/completion-designs/read, or its text as csv in a JSON body. A zip is read as a workbook (one without [Content_Types].xml is a 400), an .xls or a workbook saved with a password is a 400, and anything else is a CSV. sheet picks a workbook's sheet by name (exact, else in any case) or index from 0, else the first, with a warning when there are more; one the workbook lacks is a 400 with details.sheets. A name of digits only reads as an index, so pick a sheet by its position in sheets (include ["sheets"]), where a name over 31 characters is cut to 31 and ends in ….
Columns
Each role reads the first of its names the file has, compared lowercased with all but letters and digits dropped (Fluid (bbl/ft) is fluidbblft):
name: designname, design, completiondesign, nameformation: noviformation, targetformation, formation, targetzone, landingzone, zonefluid_bbl_per_ft: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength, fluid, fluidbblftfluid_gal_per_ft: fluidgalperft, galperft, fluidgalftproppant_lb_per_ft: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft, proppant, sand, sandlbperft, proppantlbft, sandlbftfluid_bbl_per_stage: fluidbblperstage, fluidperstage, fluidbblstageproppant_lb_per_stage: proppantlbperstage, proppantperstage, sandperstage, proppantlbstage, sandlbstagestage_length_ft: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelenclusters_per_stage: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststgfrac_rate_bbl_per_min: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm
Other columns (costs) are listed in fields and not read; clusters_per_stage and frac_rate_bbl_per_min are in columns only when the file has them. A file with no fluid or proppant column is a 400 with details.fields.
Rows
A CSV row with more cells than the header is left out.
- Rows with the same name are one design; a blank name, or one over 60 characters, leaves the row out.
- A row without a formation sets its design's values; one with a formation (any case) adds an entry to the design's
formations, at most 100 (later ones are left out). An unknown formation leaves the row out and is counted inunknown_formations. - A repeat of a name and formation, or of a name's own row, is left out, naming the row it repeats.
Values
Numbers are written as 2700 or 2.7e3, without thousands separators.
- Fluid is bbl/ft, or gal/ft divided by 42. Per-stage fluid and proppant are divided by the row's stage length (dropped with an issue without one over 0). A row with two forms reads bbl/ft over gal/ft and per ft over per stage, and the other gets an issue.
- Fluid is over 0 and under 1,000 bbl/ft and proppant over 0 and under 20,000 lb/ft; another value is dropped with an issue, and a row left with neither is left out.
- Stage length (ft), clusters per stage and frac rate (bbl/min) are kept on the design or formation entry, each dropped with an issue out of range: stage length over 0 and under 2,000 ft, clusters per stage over 0 and under 100, frac rate over 0 and under 500 bbl/min.
- A stage length that converted per-stage values is kept only on a model set whose models read it. A warning names filled stage columns the set's models don't read.
Limits
The 10 MB request body (a 413); 1,000 rows and 100 designs, each a 400 with details.max and details.count. POST /plans takes 10 designs, so a warning comes past 10, and POST /forecasts 25.
Errors
400 with details.field naming file, csv, sheet, or include and include[0] (an unknown value, with details.allowed).
Parameters
Query parameters
model_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches the base dataset; once the server retires it, a 400 naming the set answering instead.- An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in
details.allowed(published sets only oncedefaultis retired); a set that can't load, a 503 with the reason. - Plans and exports stay in their set: a call naming them (by path,
plan,ids,source.plan, a scenario'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
The file as a multipart upload, or CSV text in JSON.
filestringRequiredFile
A CSV or .xlsx workbook.
sheetstringOptionalWorkbook sheet name in any case or index from 0; absent, the first. With CSV, a 400.
includestringOptionalJSON text, as ["sheets"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged.
csvstringRequiredThe CSV or tab-separated file text.
Responses
200 OK
Named designs and every row in file order.
countintegerRequired≥ 0
Number of designs.
formatstringRequiredHow the file was read.
"csv""xlsx"columnsobjectRequiredEach role and its header as read; null when absent.
ShowHide 10 child fields
namestring or nullRequiredDesign name header or null.
formationstring or nullRequiredFormation header or null.
fluid_bbl_per_ftstring or nullRequiredFluid bbl/ft header or null.
fluid_gal_per_ftstring or nullRequiredFluid gal/ft header or null.
proppant_lb_per_ftstring or nullRequiredProppant lb/ft header or null.
fluid_bbl_per_stagestring or nullRequiredFluid per-stage header or null.
proppant_lb_per_stagestring or nullRequiredProppant per-stage header or null.
stage_length_ftstring or nullRequiredStage length header or null.
clusters_per_stagestringOptionalClusters per stage header; only when the file has the column.
frac_rate_bbl_per_minstringOptionalFrac rate header; only when the file has the column.
fieldsarray of stringsRequiredHeaders in file order.
designsarray of objectsRequiredNamed designs in first-appearance order, ready to post as designs; formations is always an array.
ShowHide 7 child fields in each item
namestring or nullOptionalup to 60 characters
Your name for the design; defaults to Design 1, Design 2, ….
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.formationsarray of objectsOptionalPer-formation overrides, each formation at most once.
ShowHide 6 child fields in each item
formationstringRequiredFormation (case-insensitive).
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.
rowsarray of objectsRequiredEvery data row in file order; blank lines are left out.
ShowHide 5 child fields in each item
idintegerRequired≥ 0
Data row from 0, in file order.
namestring or nullRequiredTrimmed name, generated Design N without a name column, or null when blank.
formationstring or nullRequiredDataset spelling when matched, else the text as written, or null when blank.
designinteger or nullRequired≥ 0
Index in designs, or null when left out.
issuesarray of stringsRequiredWhy the row was left out or a value dropped.
unknown_formationsarray of objectsRequiredMost rows first, ties in first-seen order.
ShowHide 2 child fields in each item
valuestringRequiredFirst spelling read.
rowsintegerRequired≥ 1
Rows left out.
warningsarray of stringsRequiredWorkbook warnings first, then each column with no number in it, rows left out, the warning past 10 designs, and one naming filled stage columns the model set's models don't read.
sheetstringOptionalThe sheet read; only with include ["sheets"], for a workbook.
sheetsarray of stringsOptionalEvery sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include ["sheets"], for a workbook.
Errors
| Status | When |
|---|---|
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean