{"id":22018129,"url":"https://github.com/rvflash/awql","last_synced_at":"2025-06-15T11:34:17.404Z","repository":{"id":57528717,"uuid":"47223267","full_name":"rvflash/awql","owner":"rvflash","description":"AWQL Command-Line Tool to request Google Adwords reports","archived":false,"fork":false,"pushed_at":"2018-09-27T16:27:51.000Z","size":1973,"stargazers_count":30,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-31T05:41:26.150Z","etag":null,"topics":["awql","awql-query","golang","google-adwords"],"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/rvflash.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}},"created_at":"2015-12-01T23:11:00.000Z","updated_at":"2023-01-17T22:34:53.000Z","dependencies_parsed_at":"2022-09-10T20:00:26.843Z","dependency_job_id":null,"html_url":"https://github.com/rvflash/awql","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvflash%2Fawql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvflash%2Fawql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvflash%2Fawql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvflash%2Fawql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rvflash","download_url":"https://codeload.github.com/rvflash/awql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252804219,"owners_count":21806771,"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":["awql","awql-query","golang","google-adwords"],"created_at":"2024-11-30T05:10:02.139Z","updated_at":"2025-05-07T03:10:26.817Z","avatar_url":"https://github.com/rvflash.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWQL - The AWQL Command-Line Tool\n\n[![GoDoc](https://godoc.org/github.com/rvflash/awql?status.svg)](https://godoc.org/github.com/rvflash/awql)\n[![Build Status](https://img.shields.io/travis/rvflash/awql.svg)](https://travis-ci.org/rvflash/awql)\n[![Go Report Card](https://goreportcard.com/badge/github.com/rvflash/awql?)](https://goreportcard.com/report/github.com/rvflash/awql)\n\n\nAllows to request Google Adwords API reports with AWQL language.\nIt is a simple SQL shell with input line editing capabilities. It supports interactive and non-interactive use.\nWhen used interactively, query results are presented in an ASCII-table format.\nWhen used non-interactively, the result is presented in comma-separated format. The output format or many other tricks can be changed using command options.\n\n\n## Installation\n\nIn order to improve the portability of this tool, since the v1.0.0, Awql is no longer developed in Bash and Awk but entirely in Go.\n\n`awql` requires Go 1.7.1 or later.\n\n```bash\n$ go get -u github.com/rvflash/awql\n```\n\n\n### Usage\n\n```bash\n$ awql -i \"123-456-7890\"\nWelcome to the AWQL monitor. Commands end with ; or \\G.\nYour AWQL connection implicitly excludes zero impressions.\nAdwords API version: v201809\n    \nReading table information for completion of table and column names.\nYou can turn off this feature to get a quicker startup with -A\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nawql\u003e select CampaignName, Clicks, Impressions, Cost, Amount, TrackingUrlTemplate from CAMPAIGN_PERFORMANCE_REPORT limit 5;\n+--------------+---------+--------------+------------+-----------+--------------------+\n| Campaign     | Clicks  | Impressions  | Cost       | Budget    | Tracking template  |\n+--------------+---------+--------------+------------+-----------+--------------------+\n| Campaign #1  | 526     | 42006        | 456020000  | 33000000  | --                 |\n| Campaign #2  | 0       | 0            | 0          | 33000000  | --                 |\n| Campaign #3  | 0       | 0            | 0          | 33000000  | --                 |\n| Campaign #4  | 4       | 310          | 1210000    | 1000000   | --                 |\n| Campaign #5  | 196     | 13168        | 242870000  | 26000000  | --                 |\n+--------------+---------+--------------+------------+-----------+--------------------+\n5 rows in set (0.322 sec)\n```\n \n### Quick start\n\nSet up credentials, on the first execution of the tool, by filling the mandatory fields (client ID, refresh token, etc.).\nFor more information about how to create a access token to Google Adwords, see the [wiki on Google OAuth 2.0](https://github.com/rvflash/awql/wiki/Installation).\n\nOtherwise, with options `-T` to set the Google OAuth access token and `-D` to set the Google OAuth developer token, you can run AWQL queries in single shot mode, until the expriration on the token.  \n\n\n## Features\n\n* Auto-refreshed the Google access token with the Google OAuth2 services.\n* When used interactively, adds the management of historic of queries with arrow keys. Can be disable with option `-A`.\n* Adds to AWQL grammar for requesting Adwords reports the following SQL clauses to `SELECT` statement: `LIMIT`, `GROUP BY` and `ORDER BY`.\n* Also offers the SQL methods `DESC [FULL]`, `SHOW [FULL] TABLES [LIKE|WITH]` and `CREATE [OR REPLACE] VIEW`.\n* Adds management of `\\G` modifier to display result vertically (each column on a line)\n* Also adds the aggregate functions: `AVG`, `COUNT`, `MAX`, `MIN`, `SUM` and `DISTINCT` keyword.\n* The view offers possibility to filter the AWQL reports to create your own report, with only the columns and scope that interest you.\n* `*` can be used as shorthand to select all columns from all views\n* Caching data in order to don't request Google Adwords services with queries already fetch in the day. This feature can be enable with option `-c`. \n* By default, all calls implicitly excludes zero impressions. This behavior can be changed with the option `-z`.\n* Uses by default the last available version of the Google Adwords API: v201809.\n\n## SQL methods adding to AWQL grammar\n\n\n#### DESC [FULL] table_name [column_name]\n\n```bash\n$ awql\u003e desc CAMPAIGN_SHARED_SET_REPORT;\n+------------------------+----------------+-----+---------------------------+\n| Field                  | Type           | Key | Supports_Zero_Impressions |\n+------------------------+----------------+-----+---------------------------+\n| AccountDescriptiveName | String         |     | YES                       |\n| CampaignId             | Long           |     | YES                       |\n| CampaignName           | String         |     | YES                       |\n| CampaignStatus         | CampaignStatus |     | YES                       |\n| ExternalCustomerId     | Long           |     | YES                       |\n| SharedSetName          | String         | PRI | YES                       |\n| SharedSetType          | SharedSetType  |     | YES                       |\n| Status                 | Status         |     | YES                       |\n+------------------------+----------------+-----+---------------------------+\n8 rows in set (0.000 sec)\n```\n\n\n#### SELECT ... \\G\n\n```bash\n$ awql\u003e select CampaignName, Clicks, Impressions, Cost, Amount, TrackingUrlTemplate from CAMPAIGN_PERFORMANCE_REPORT limit 1\\G\n**************************** 1. row ****************************\n       CampaignName: Campagne Shopping\n             Clicks: 276526\n        Impressions: 10293554\n               Cost: 179673040000\n             Amount: 500000000\nTrackingUrlTemplate:  --\n1 row in set (1.109 sec)\n```\n\nThe FULL modifier is supported such that DESC FULL displays two more columns with enum values and uncompatibles fields list.\n\n```bash\n$ awql\u003e desc full CAMPAIGN_PERFORMANCE_REPORT EnhancedCpcEnabled;\n+--------------------+------+-----+---------------------------+-------------+---------------------+\n| Field              | Type | Key | Supports_Zero_Impressions | Enum        | Not_compatible_with |\n+--------------------+------+-----+---------------------------+-------------+---------------------+\n| EnhancedCpcEnabled | Enum |     | YES                       | TRUE, FALSE |                     |\n+--------------------+------+-----+---------------------------+-------------+---------------------+\n1 row in set (0.000 sec)\n```\n\n\n#### SHOW [FULL] TABLES [LIKE 'pattern']\n\n```bash\n$ awql\u003e show tables like \"CAMPAIGN%\";\n+-------------------------------------------------+\n| Tables_in_v201809                               |\n+-------------------------------------------------+\n| CAMPAIGN_AD_SCHEDULE_TARGET_REPORT              |\n| CAMPAIGN_LOCATION_TARGET_REPORT                 |\n| CAMPAIGN_NEGATIVE_KEYWORDS_PERFORMANCE_REPORT   |\n| CAMPAIGN_NEGATIVE_LOCATIONS_REPORT              |\n| CAMPAIGN_NEGATIVE_PLACEMENTS_PERFORMANCE_REPORT |\n| CAMPAIGN_PERFORMANCE_REPORT                     |\n| CAMPAIGN_SHARED_SET_REPORT                      |\n+-------------------------------------------------+\n7 rows in set (0.001 sec)\n```\n\nThe FULL modifier is supported such that SHOW FULL TABLES displays a second output column with the type of table.\n\n```bash\n$ awql\u003e show full tables like \"ADGROUP%\";\n+----------------------------+------------+\n| Tables_in_v201809          | Table_type |\n+----------------------------+------------+\n| ADGROUP_PERFORMANCE_REPORT | BASE TABLE |\n+----------------------------+------------+\n1 row in set (0.000 sec)\n```\n\n\n#### SHOW TABLES [WITH 'pattern']\n\n```bash\n$ awql\u003e show full tables with Url;\n+--------------------------+------------+\n| Tables_in_v201809        | Table_type |\n+--------------------------+------------+\n| KEYWORDLESS_QUERY_REPORT | BASE TABLE |\n| URL_PERFORMANCE_REPORT   | BASE TABLE |\n+--------------------------+------------+\n2 rows in set (0.000 sec)\n```\n\n\n#### CREATE [OR REPLACE] VIEW view_name [(column_list)] AS select_statement\n\n```bash\n$ awql\u003e create view CAMPAIGN_COST_WEEK (name, cost) as select CampaignName, Cost from CAMPAIGN_PERFORMANCE_REPORT during LAST_WEEK;\n```\n\n\n#### SELECT * FROM view_name\n\nOnly works on a view. Adwords tables are not designed for that. Too much columns and fields incompatibles between them.\n\n```bash\n$ awql\u003e select * from CAMPAIGN_COST_WEEK;\n+-------------+------------+\n| name        | cost       |\n+-------------+------------+\n| Campaign #1 | 60000      |\n| Campaign #2 | 10000      |\n| Campaign #3 | 20000      |\n+-------------+------------+\n```\n\n\n#### SELECT ... LIMIT [offset,] row_count\n\n```bash\n$ awql\u003e select CampaignName, Clicks, Impressions, Cost, TrackingUrlTemplate from CAMPAIGN_PERFORMANCE_REPORT order by 3 limit 3;\n+-------------+---------+--------------+------------+--------------------+\n| Campaign    | Clicks  | Impressions  | Cost       | Tracking template  |\n+-------------+---------+--------------+------------+--------------------+\n| Campaign #1 | 12      | 1289         | 9760000    | --                 |\n| Campaign #2 | 8       | 1490         | 7010000    | --                 |\n| Campaign #3 | 432     | 26469        | 450420000  | --                 |\n+-------------+---------+--------------+------------+--------------------+\n3 rows in set (0.01 sec)\n```\n\n\n#### SELECT ... ORDER BY column_name [ASC | DESC]\n\n```bash\n$ awql\u003e SELECT CampaignName, Clicks, Impressions FROM CAMPAIGN_PERFORMANCE_REPORT ORDER BY Impressions DESC;\n+--------------+---------+--------------+\n| Campaign     | Clicks  | Impressions  |\n+--------------+---------+--------------+\n| Campaign #12 | 526     | 42006        |\n| Campaign #3  | 432     | 26469        |\n| Campaign #5  | 196     | 13168        |\n| Campaign #10 | 145     | 8646         |\n| Campaign #2  | 8       | 1490         |\n| Campaign #1  | 12      | 1289         |\n| Campaign #4  | 4       | 310          |\n| Campaign #6  | 3       | 295          |\n| Campaign #9  | 3       | 259          |\n| Campaign #13 | 4       | 248          |\n| Campaign #11 | 10      | 237          |\n| Campaign #7  | 0       | 9            |\n| Campaign #14 | 0       | 9            |\n| Campaign #8  | 0       | 2            |\n+--------------+---------+--------------+\n14 rows in set (0.801 sec)\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvflash%2Fawql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frvflash%2Fawql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvflash%2Fawql/lists"}