{"id":13639101,"url":"https://github.com/maragkakislab/samql","last_synced_at":"2026-05-12T05:05:11.805Z","repository":{"id":51132142,"uuid":"143456025","full_name":"maragkakislab/samql","owner":"maragkakislab","description":"SQL-like query language for the SAM/BAM file format","archived":false,"fork":false,"pushed_at":"2023-09-20T16:58:03.000Z","size":67,"stargazers_count":26,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-03T01:13:48.111Z","etag":null,"topics":["bam","bioinformatics","go","sam","sequencing","sql"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maragkakislab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-08-03T17:36:30.000Z","updated_at":"2024-07-22T12:02:00.000Z","dependencies_parsed_at":"2022-09-26T18:51:01.463Z","dependency_job_id":"15ee8a71-2691-4662-a8a3-685018198a41","html_url":"https://github.com/maragkakislab/samql","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maragkakislab%2Fsamql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maragkakislab%2Fsamql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maragkakislab%2Fsamql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maragkakislab%2Fsamql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maragkakislab","download_url":"https://codeload.github.com/maragkakislab/samql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223810267,"owners_count":17206725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bam","bioinformatics","go","sam","sequencing","sql"],"created_at":"2024-08-02T01:00:57.665Z","updated_at":"2026-05-12T05:05:06.761Z","avatar_url":"https://github.com/maragkakislab.png","language":"Go","funding_links":[],"categories":["Proteomics and Genomics Analysis"],"sub_categories":[],"readme":"# samql [![Go Report Card](https://goreportcard.com/badge/github.com/maragkakislab/samql)](https://goreportcard.com/report/github.com/maragkakislab/samql) [![GoDoc](https://godoc.org/github.com/maragkakislab/samql?status.svg)](https://godoc.org/github.com/maragkakislab/samql)\nSQL-like query language for the SAM/BAM file format\n\n## Install\n\nDownload the latest executable:\n\n[Latest](https://github.com/maragkakislab/samql/releases/latest/).\n\nOtherwise, to install the Go library and executable:\n\n`go get github.com/maragkakislab/samql/...`\n\n\n## Objective\n\nTo provide a command line utility and a clean API for filtering SAM/BAM files\nusing simple SQL-like commands. The samql command showcases the envisioned\nfunctionality.\n\n## Usage\n\n```bash\nFilters a SAM/BAM file using the SQL clause provided\nsamql 1.7\nUsage: samql [--where WHERE] [--count] [--sam] [--parr PARR] [--obam] INPUT [INPUT ...]\n\nPositional arguments:\n  INPUT                  file (- for STDIN)\n\nOptions:\n  --where WHERE          SQL clause to match records\n  --count, -c            print only the count of matching records\n  --sam, -S              interpret input as SAM, otherwise BAM\n  --parr PARR, -p PARR   Number of cores for parallelization. Uses all available, if not provided.\n  --obam, -b             Output BAM\n  --help, -h             display this help and exit\n  --version              display version and exit\n```\n\n## Examples\n\n```bash\n# Simple\nsamql --where \"RNAME = chr1\" test.bam    # Reference name is \"chr1\"\nsamql --where \"QNAME = read1\" test.bam   # Query name is \"read1\"\nsamql --where \"POS \u003e 100\" test.bam       # Position (0-based) greater than 100\nsamql --where \"REVERSE\" test.bam         # Negative strand\nsamql --where \"FLAG \u0026 16 = 16\" test.bam  # Ditto using flag arithmetics\n\n# More than one files\nsamql --where \"REVERSE\" test1.bam test2.bam # Reads are returned in the order of the files\n\n# Regex\nsamql --where \"CIGAR =~ /^15M/\" test.bam # Alignment starts with 15 matches\n\n# More complex\nsamql --where \"RNAME = chr1 OR QNAME = read1 AND POS \u003e 100\" test.bam\n\n# Just counting\nsamql -c --where \"RNAME = chr1\" test.bam\n\n# Very complex\n# Uniquely mapped reads, with first pair on chr1 after\n# position 1000000 and second pair on chr1 or chrX that\n# start with 15 matches/mismatches, are shorter than 75 nts\n# or begin with an ATG and are located on the reverse strand.\n\nsamql --where \"(RNAME = 'chr1' AND POS \u003e 1000000) AND \\\n               (RNEXT = 'chr1' OR RNEXT = 'chrX') AND \\\n               NH:i = 1 AND \\\n               CIGAR =~ /^15M/ AND \\\n               (LENGTH \u003c 75 OR SEQ =~ /^ATG/) AND \\\n               PAIRED AND REVERSE\"\n```\n\n## Keywords\n\n```Go\nQNAME         // QNAME corresponds to the SAM record query name.\nFLAG          // FLAG corresponds to the SAM record alignment flag.\nRNAME         // RNAME corresponds to the SAM record reference name\nPOS           // POS corresponds to the SAM record position (0-based).\nMAPQ          // MAPQ corresponds to the SAM record mapping quality.\nCIGAR         // CIGAR corresponds to the SAM record CIGAR string.\nRNEXT         // RNEXT corresponds to the reference name of the mate read.\nPNEXT         // PNEXT corresponds to the position of the mate read.\nTLEN          // TLEN corresponds to SAM record template length.\nSEQ           // SEQ corresponds to SAM record segment sequence.\nQUAL          // QUAL corresponds to SAM record quality.\nLENGTH        // LENGTH corresponds to the alignment length.\nPAIRED        // PAIRED corresponds to SAM flag 0x1.\nPROPERPAIR    // PROPERPAIR corresponds to SAM flag 0x2.\nUNMAPPED      // UNMAPPED corresponds to SAM flag 0x4.\nMATEUNMAPPED  // MATEUNMAPPED corresponds to SAM flag 0x8.\nREVERSE       // REVERSE corresponds to SAM flag 0x10.\nMATEREVERSE   // MATEREVERSE corresponds to SAM flag 0x20.\nREAD1         // READ1 corresponds to SAM flag 0x40.\nREAD2         // READ2 corresponds to SAM flag 0x80.\nSECONDARY     // SECONDARY corresponds to SAM flag 0x100.\nQCFAIL        // QCFAIL corresponds to SAM flag 0x200.\nDUPLICATE     // DUPLICATE corresponds to SAM flag 0x400.\nSUPPLEMENTARY // SUPPLEMENTARY corresponds to SAM flag 0x800.\nEND           // END corresponds to the alignment end.\n```\n\n\n## API example\n\n```Go\n// Open github.com/biogo/hts/sam reader\nf := os.Open(\"test.sam\")\nsr, _ := sam.NewReader(f)\n\n// Do the filtering\nr := samql.NewReader(sr)\nfilter, _ := samql.Where(\"POS = 1\")\nr.Filters = append(r.Filters, filter)\nfor {\n\trec, err := r.Read()\n\tif err != nil {\n\t\tif err == io.EOF {\n\t\t\tbreak\n\t\t}\n\t\tpanic(err)\n\t}\n\n\t// Do sth with rec\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaragkakislab%2Fsamql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaragkakislab%2Fsamql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaragkakislab%2Fsamql/lists"}