Fetching a record from a database
You do not always start from a file. Often you start from a name you half-remember, an accession in a methods section, or a coordinate range on a chromosome. This page is about getting that into the workbench as a real, editable sequence — and about the three or four places where public sequence databases will mislead you if you let them.
Open it from the lobby (Start a project → Fetch from database) or, once you are in the editor, from File → Fetch from database…. It is the same dialog everywhere, and whatever it returns is added to the project you are already in.
There are three ways in, and they answer different questions.
| Tab | The question it answers |
|---|---|
| Search | "I know roughly what I want, but not its accession." |
| Accession | "I have the identifier." |
| Organism | "I want a window of a chromosome, and I do not want to hunt for the replicon's accession first." |
Search — one query, several archives at once
The Search tab as it opens. The row under the box is the set of archives the query goes to; switch any of them off and it stops being queried. The empty state names the same set again and offers four real queries to start from, so the box is never a blank prompt. The ? beside the settings cog says where the records come from and which sources need an account.
The query goes to every selected archive in parallel, and each answers on its own schedule. Eight are wired, and they are not interchangeable:
| Archive | What it holds, and when you want it |
|---|---|
| NCBI Nucleotide | GenBank and RefSeq nucleotide records — the default for a gene, an mRNA, a plasmid |
| NCBI Protein | GenPept: RefSeq proteins and the conceptual translations of GenBank CDS |
| ENA | The same INSDC content from the European partner archive, in EMBL-native form |
| ENA WGS sets | Draft and whole-genome shotgun assemblies — a genome that arrives as thousands of contigs rather than one molecule |
| ENA TSA/TLS sets | Transcriptome shotgun assemblies and targeted locus studies |
| ENA features | Individual annotated features — a single coding sequence or non-coding RNA, addressable and retrievable on its own |
| UniProtKB | Curated protein knowledge — Swiss-Prot entries with their evidence, plus unreviewed TrEMBL |
| iGEM Registry | Standard biological parts — promoters, ribosome binding sites, terminators, coding sequences and pSB backbones, the vocabulary synthetic-biology constructs are assembled from |
Standard parts are a different kind of record
Searching the iGEM Registry for T7 promoter. Each row carries the part's length, its status, and
its role as a Sequence Ontology term — Promoter (SO:0000167), CDS (SO:0000316) — so the row
says what the part IS in a controlled vocabulary rather than only what someone named it. Only the
Registry is switched on here; with several archives selected the rows interleave and are deduped by
accession.
The five INSDC and UniProt archives above hold observed biology — sequences someone determined from an organism. The iGEM Registry holds designed biology: parts intended to be composed, each one a promoter, ribosome binding site, coding sequence, terminator or backbone that other people have already built with.
Three things follow from that, and they change how you read a result:
- There is no source organism, because a standard part is a construct rather than an isolate.
Where an INSDC row tells you the species, a Registry row tells you the role and how many
designs have used it —
Used in 2039 designsis the closest thing the Registry has to a confidence measure, and it is worth more than a description. - Parts are licensed, which sequences in a public archive generally are not. Each part states
its licence by SPDX identifier (
cc-by-4.0,cc0-1.0, and so on) taken from the Registry's own licence table, because a part you compose into a construct is someone's work and the terms travel with it. - The record you get is the Registry's own, not a reconstruction. The part arrives as the GenBank file the Registry itself writes, with its role already annotated as a feature, so it opens with the same coordinates and the same annotation the Registry publishes.
Part identifiers are written BBa_R0040 in every paper and wiki you will read, and that is what to
type — including the backbones, which use the pSB prefix (pSB1C3). An identifier that is not a
part id is refused before anything is sent, with the reason given:
NC_005816 is a perfectly good GenBank accession and not a part id, so the Registry tab says so
rather than sending a request that would fail.
INSDC means NCBI and ENA hold the same records. GenBank, ENA and DDBJ exchange data daily, so a search across both routinely returns the same sequence twice under the same accession. Those are merged into one row, and anything one archive knows that the other does not is folded into the survivor — which is why a genome assembly found through NCBI can still show you the assembled size that only ENA publishes. Merging happens within a molecule kind only: a protein and a nucleotide record that happen to share an accession string are different molecules and stay separate rows.
Each row shows everything the archive actually reported — not a fixed set of fields we chose. For an NCBI record that includes the source qualifiers people usually have to open the record to see (strain, host, country, isolation source, collection date); for a UniProt entry, the names, lineage, mass, keywords, feature counts and cross-references to PDB, Ensembl, Pfam and the rest, each linked to its authority. The Fields control groups them so you can collapse what you do not care about.
Asking for a gene and getting the gene
The archives above answer with whole records: the plasmid, the chromosome, the mRNA entry. That is usually right, and sometimes it is precisely wrong. If you want the beta-globin coding sequence, a whole-record search hands you the genomic entry it sits inside, and you are left finding the CDS within it and cutting it out by coordinate.
ENA features answers the other question. INSDC records are annotated, and each annotated feature
carries its own accession — so a coding sequence is itself a retrievable record, with its own length,
its own gene name, its own product name and, where it is protein-coding, its own protein id. Search
globin here and you get AAA16334, Homo sapiens (human) beta-globin, 444 bp, gene HBB: the
coding sequence, not the entry containing it.
Reach for it when:
- you want the CDS or the ncRNA rather than the record around it — a gene to codon-optimise, a sequence to align, a feature to use as a Gibson fragment;
- you are comparing the same gene across organisms, where whole records differ in scope and features do not;
- you know the product name but not the accession.
productandgeneare searchable fields here, and on a whole-record search they are buried in the description.
beta-lactamase Escherichia coli, with every archive except ENA features switched off. Eleven
annotated coding sequences, each with its own accession, length, gene name (blaCTX-M-15, bla,
blaVIM-19), product, protein id and the parent record it was annotated on. Add to project puts
the CDS itself into the editor, not the plasmid around it.
Two things to expect. A feature accession looks unlike a record accession (AAA16334, not
NC_005816), and it resolves at the European archive rather than at NCBI, which is where the file
comes from when you open it. And a feature is a fragment of a molecule: it opens linear, with no
topology to inherit, because it never was a molecule of its own.
What an ENA search actually matches
Worth knowing, because it is not how a web search behaves. ENA has no free-text index and no relevance ranking. Every word you type becomes a requirement, and each one is matched as a substring of the fields the archive indexes: the record's description, its organism name, and — for features — its gene and product names. A word that appears only in the annotation body, the reference block or a qualifier we do not consult will not match, however clearly it is in the record.
Two consequences worth carrying:
- Punctuation inside a word is treated as a gap, not a character. The archive does not match
across a hyphen, and its own curators are inconsistent about them: the records in the figure above
describe themselves as "CTX-M-15 betalactamase", unhyphenated, while the enzyme is universally
written beta-lactamase. You do not have to think about this —
beta-lactamaseandbetalactamasefind the same records — but it explains why a short stem (lactamase) is often the better query than a precise full name. - An empty result is not always an answer. ENA occasionally responds to a slow search with an empty result set rather than an error: measured over ten identical queries, two came back empty, and both were the slow ones. If a search took a noticeable while and found nothing, run it again unchanged before concluding the archive has no such record. The panel says so when it happens.
And because the archives are queried in parallel and answer on their own schedule, an archive that has not answered within 45 seconds is dropped and named beneath the results, rather than holding back what the others already found.
Non-coding features come back from the same source and the same search. They are one control rather than two, because a search for a name rarely knows in advance whether the answer is protein-coding.
The number on the row is not always base pairs
This is the trap worth knowing before you import anything, because it is silent and it is large.
A master record for a whole-genome project — a WGS, TSA or TLS accession such as
ACEPME000000000 — holds no sequence at all. It is a pointer to the component contigs. Its
LOCUS line does not report bases; it reports a record count, written rc. NCBI's summary
service returns that count in the very same field that carries a base count for every ordinary
record, so a naive reading turns "449 contigs" into "449 bp", and a 5.3 Mbp genome looks like a short
PCR product.
Worse, the unit depends on who built the master: GenBank and DDBJ masters report a record count,
while RefSeq recomputes the master with the assembled total, so a NZ_… master really is base pairs.
So the row never prints an ambiguous "length". It tells you which of three things it knows — the bases the record actually holds, the number of contigs it points at, and the size you get once those contigs are assembled — and says so in words: "449 contigs → 5.30 Mbp assembled". A master row also states what importing will do before you click it, because importing one fetches every component contig and joins them into a single multi-contig sequence.
Tip. If a hit looks implausibly short for what it claims to be, check whether the accession ends in a run of zeros. That is the shape of a master record.
Big records
The dialog warns you on the row, before you open it when a record is large enough to change your afternoon — a slow canvas, long pauses, or a tab that runs out of memory — and puts that record's own download links right next to the warning. Downloading the file and keeping it is often the better move for a whole chromosome; the workbench is not trying to be the place you store a genome.
Accession — when you have the identifier
A window of NC_005816. The line under the controls is the exact request that will be sent — it is
shown before anything is fetched, not after.
Seven targets: NCBI Nucleotide, NCBI Protein, ENA, UniProtKB, the iGEM Registry, Addgene, and EBI Dbfetch, which is a single endpoint in front of a large family of EMBL-EBI databases — RefSeq, Ensembl and Ensembl Genomes, PDB, AlphaFold, InterPro, IMGT/HLA, IPD-KIR and IPD-MHC, ChEMBL, HGNC, NCBI Taxonomy, MEDLINE and the patent protein sets among them. That list, each database's formats, its default format and its own example identifiers are read from EBI's registry when you open the tab, so it is whatever EBI serves today rather than a list we keep. Formats the workbench cannot open are still offered, labelled as downloads rather than handed to a parser that would fail on them.
Addgene, by deposit number
Addgene is where a great many published plasmids actually live, and it is addressed the way papers
cite it: by deposit number. Type 50005 (the number in the plasmid's address, not its name) and the
deposit's own sequence file is fetched and opened as an ordinary editable plasmid.
A name typed here is refused before anything is sent, because Addgene numbers a deposit with digits only and a name would simply 404.
Deposit 50005 is real and its map is public; its sequence file is what the account gates. The tab
says which of those happened, in Addgene's own terms, and points at the page where a signed-in
download is the same file.
Two things are worth knowing about what comes back:
- The file is the depositor's, in the form Addgene holds it. A deposit may publish a GenBank
file, a SnapGene
.dna, or both; whichever is served is what you get, and the workbench reads both. Nothing is reconstructed from a page. - Since 18 August 2026 Addgene asks for a free account before it hands over sequence data. When it declines, you are told so in those words, with a link to the deposit's own page where a signed-in download is the same file. The deposit's maps and metadata are unaffected, and a refusal is never an empty result you have to interpret.
Fetching part of a record
You rarely want a whole chromosome. Give the accession a window — a start, an end, and a strand — and only that window is retrieved.
Coordinates are the ones the databases print: 1-based and inclusive. 5000..7000 is 2,001 bases
and includes both ends. Windows are always written low-to-high whichever strand you choose; the minus
strand is expressed as complement(5000..7000) and comes back reverse-complemented, which is the
same convention a GenBank feature location uses.
Two things are refused before any request is sent, with the reason next to the control that caused it, rather than after a download that was never going to work:
- A backwards range (
7000..5000). You are told to usecomplement(5000..7000)if what you wanted was the minus strand. - A half-filled window — a start with no end. This previously fetched the entire record without saying so, which is the failure that costs you a 5 Mbp download you did not ask for.
You can also type the window straight into the identifier box in any of the forms the archives
themselves accept: NC_005816 REGION: 5000..7000, NM_005546 REGION: complement(1..100),
21614549:1-100. The panel and the fetch agree about what those mean because they ask the same
parser.
Rate limits, and the identity box
NCBI asks automated requesters to identify themselves, and lifts the limit from 3 to 10 requests per second for anyone who does. The gear icon in the dialog takes an email address and an optional API key from your NCBI account; both stay in this browser and are sent only to NCBI.
Optional, and worth setting if you page through search results or import a WGS master, which fetches many contigs in sequence.
If you are working through a lot of records and start seeing failures, this is the first thing to set.
Organism — a window of a chromosome, without hunting for the accession
Type an organism name or a taxonomy id and the picker resolves it against NCBI's taxonomy, lists that organism's current assemblies (the designated reference genome first), lets you pick a replicon — chromosome, plasmid, organelle — and fetches a window of it.
Nothing here is a stored list: the organisms, the assemblies and the replicon accessions are all resolved live, so you get the current reference assembly rather than one that was current when someone wrote a mapping table. A single region fetch is capped at 5 Mbp; past that you are asked to narrow the window rather than being left to discover the limit by waiting.
If you are not sure where to start, the tab offers a few real organisms to click; they run the same live lookup as anything you type, and you can edit the name afterwards.
This is the fastest route to a CRISPR off-target search space, or to the neighbourhood of a locus you want to look at in context. The guide designer can now do the whole thing without leaving its panel: under Off-target search it offers Fetch a search space…, which opens this same dialog and puts the record you choose straight into the subject slot. The panel then reads, for example, Searching 4,701 bp of BBa_255DIYN6, and the search runs against it. A protein record is refused there with the reason, since an off-target search looks for PAM-adjacent matches in DNA.
What the file remembers
A fetched record becomes an ordinary file in your project, in its own format — but it also carries where it came from: the authority, the identifier, the exact URL, the date it was retrieved, and, if you fetched a window, which bases of the parent it is. The file's details show that as a sentence in the coordinates you typed: "5,000–7,000 of NC_005816 (+ strand)".
That matters more than it sounds. A FASTA of a 2,001 bp region on your disk is anonymous six months later; the same file here still knows it is a slice of a named record, taken on a named day. When you share a project, fetched records travel as their accession rather than as bytes — the person opening it resolves them from the authority themselves.
Is your copy still the current one?
Sequence records get revised. RefSeq re-curates, an assembly is corrected, a submitter fixes a
frameshift — and the identifier does not change, only the number after the dot does. E. coli K-12
MG1655 is 4,639,675 bases at NC_000913.2 and 4,641,652 at .3: a corrected genome, same accession,
nearly two thousand bases different.
The trap is that re-downloading does not tell you. The archives honour a pinned version
literally, so asking for NC_000913.2 returns the 2013 record for ever, however long ago that was
superseded. A stored URL answers "can I get these exact bytes again" — which is what sharing needs —
and never "is this still current".
A part fetched from the iGEM Registry, open on the canvas with its features and cut sites. The
details carry where it came from — as a link back to the authority — when it was taken, and the
revision question, answered here with the reason the Registry has no answer to give.
So the file's details carry a Revision row with a Check for a newer one button. It asks the authority about the base accession, and tells you one of five things:
| Answer | What it means |
|---|---|
| Up to date | The authority serves the version you hold |
| A newer revision exists | With both version numbers, and the new length when the sequence actually changed |
| The record was withdrawn | The authority no longer serves this accession — deleted, or folded into another entry. It says which, in the authority's own words |
| Nothing to compare | Your copy was stored without a version, so there is no revision to compare it to |
| The authority publishes no revision | Addgene numbers a deposit rather than versioning it; an iGEM part is replaced by a new part, never revised in place |
A stored NM_001178493.1 against NCBI's current version 3. Both numbers are shown, because "you
are behind" is not useful without saying by how much — and the action adds the new one rather than
replacing yours.
Where a newer revision exists, one click adds it to the project beside the copy you have — never over it. Your annotations, edits and the analyses that reference them are untouched, and you can align the two to see what moved.
The other answer, and the one worth checking before a submission: NC_005816.1 is what NCBI serves
today.
A withdrawn record is an answer, not a failure. An accession can stop existing: it is deleted, or it is merged into another entry that absorbed it. Neither case 404s — the text routes hand back an empty record and the JSON route hands back a stub — so a tool that does not look reports "no sequence" or "could not check", and both point away from what happened. Here the row states the authority's own reason, and where the record still is: for a merge, the entry yours became, with a one-click Add for it; for a deletion, the archive that still serves it, and the UniParc identifier the sequence itself survives under. The whole path, and how to open an old release from the archive, is in UniProt entries.
Typing a version fetches that version. NM_001178493.1 gets you release 1, not whatever is
current — which is what reproducing a published result needs, since a paper's methods pin the
version the authors used, not the one you would download today.
One case is deliberately refused: a window. If your file is bases 5,000–7,000 of a record, the same span of a newer revision is not necessarily the same bases — 1,977 bases were inserted somewhere in that E. coli genome, and every coordinate past the first of them denotes something different. Rather than hand back a different sequence wearing your label, the check says so and sends you to choose the window against the new revision.
Which authorities answer, and with what:
- NCBI publishes the current
accession.versionfor both nucleotide and protein records. - ENA carries the sequence version on the record's own first line.
- UniProtKB counts two things separately, and so do we: the sequence version rises only when the residues change, while the entry version rises on every annotation edit. An entry at version 160 whose sequence has been unchanged since version 2 is up to date, not 158 revisions behind.
One deliberate exception: an assembled WGS genome is not stamped with a single accession, because no single accession returns those bytes. It was built from many.
What it cannot reach, and why
Stated rather than omitted, because a missing source reads as an oversight:
| Not reachable | Why |
|---|---|
| Benchling, Google Drive | These are per-user accounts rather than public archives — the missing piece is somewhere to keep your credentials, not a way to fetch |
| SynBioHub | Login-gated, including the collections it describes as public |
Both come to the same thing: they need your account, not a different way of asking. That is a question about where credentials live in an application that keeps your data on your own machine, and it is not answered yet. Until it is, those records reach a project the same way any file does — download it from them, open it here.
Addgene is wired (above) and sits between the two cases: its deposit metadata and maps are open, while its sequence files have expected a free account since 18 August 2026. The tab fetches what the repository serves and reports what it declines, in Addgene's own terms.
Most of what the dialog offers is fetched straight from the authority by your browser: nothing is routed through a server of ours, and nothing about what you searched for leaves your machine except the query itself, going to the archive that answers it.
Two sources are the exception, and they are worth knowing about: the iGEM Registry and Addgene. Neither publishes cross-origin headers, which means a browser is not permitted to read them directly no matter how the request is formed. Their records therefore travel through a narrow relay belonging to this app, which is allowed to talk to those hosts and nothing else. The practical consequence for you: an iGEM part id, or an Addgene deposit number, is what passes through infrastructure rather than going straight to the source. Everything else — NCBI, ENA, UniProtKB, the EBI gateway and the organism window — goes browser-direct. Your sequences are still never sent anywhere.
NCBI, ENA and UniProtKB each publish those headers, so nothing stands between your browser and the archive for them.
Pasting an accession where a sequence goes
Methods sections cite accessions, not sequences, so the natural thing is to copy NM_000546.6 and
paste it into a tool's sequence box. The box recognises that what arrived is one identifier rather
than bases, leaves it exactly as you pasted it, and offers Fetch the record underneath. That
opens this dialog with the identifier already searched across every archive that holds the box's
kind of molecule: the nucleotide archives for a DNA box, NCBI Protein and UniProtKB for a protein
box. Pick the record and its sequence replaces the identifier in the box.
The box does not decide which archive an identifier belongs to. Accession formats overlap
(AF086833 and P04637 are both plausible in more than one archive), so the archives answer and
you choose. A record of the wrong molecule is refused with its name: a UniProt entry offered to a
DNA box says it is a protein rather than filling the box with amino-acid letters that happen to be
legal nucleotide ambiguity codes. Keep as typed dismisses the offer and leaves the identifier in
the box.
The same three questions, without the dialog
Each of the three tabs asks a different question, and each is available to a pipeline or to the assistant as well as to your hands — with the same archives, the same defaults and the same refusals.
- Which record do I want? The federated search, from a phrase. It returns the matching accessions with the organism, length and molecule type each archive reports, and names any archive that could not answer rather than quietly returning a shorter list.
- Which chromosome does this species have? An organism resolves to its published assemblies — reference genome first — and each assembly to its chromosomes, plasmids and organelles, with every accession and length. Ask for Saccharomyces cerevisiae S288C and you get four current assemblies and seventeen replicons: sixteen nuclear chromosomes and the mitochondrion.
- Give me that one. The accession fetch, with an optional window.
They chain in that order, which is how you get a window of a chromosome starting from nothing but a
species name — and the region arithmetic is the same 1-based inclusive convention described above
wherever you run it: 360000..370000 of the E. coli K-12 chromosome is 10,001 bases, asked for by
hand or asked for by a pipeline.
The science this rests on
Accession parsing, the region and strand arithmetic, and the composition of the request are not re-derived here: they follow pydna and QUEEN, the reference implementations biologists already use for exactly this, and the workbench's results are checked against them record by record — including the cases where those libraries deliberately raise an error rather than guess, such as an inverted window. The assembled-size figures for whole-genome sets come from ENA, which is the authority that publishes them.
Coordinates are the one place a sequence tool can be quietly wrong for months, so the window you typed, the window that is requested, and the window recorded in the file are all derived from one another rather than computed three times.
Next
- Files and formats — what happens to a record once it is in, and what each format keeps.
- The workbench tour — where the rest of the editor lives.
- CRISPR guide → validation — a workflow that usually starts with a fetched region.
Files and formats
83 formats across 138 extensions, all parsed in your browser, and 29 of them written back out. This page is about what happens to your file when it arrives — what opens as what, what each format keeps, what can be converted into what, and the five cases that will not open at all.
The copilot
Ask a question about the construct that is open, or hand the workbench a job. It uses the same tools you do, on the same molecule, and asks before it changes anything.