> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Facebook Pages as a data source
> Bring data from Facebook Pages to Nekt.
Facebook Pages is Meta's platform for businesses, brands, and public figures to create a presence on Facebook. It enables organizations to share updates, engage with followers, receive reviews, and track page performance through comprehensive insights and analytics.
## Configuring Facebook Pages as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Facebook Pages option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need to authorize Nekt to access your Facebook Pages data. Click on the `Facebook Authorization` button and log in with your Facebook account. Grant the necessary permissions for the pages you want to extract data from. After authentication, select the specific Page for this source and define a start date for data retrieval.
The user authorizing the connection must have admin or editor access to the Page to successfully exchange the user token for a page access token.
The following configurations are available:
* **Page ID**: The Facebook Page ID to sync data from. This field is automatically populated with the Page ID you select in the dropdown menu.
* **Start Date**: The earliest date from which records will be synced.
* **Lookback Window**: (Default: 28 days) The number of days to look back for incremental sync. Since post engagement metrics can change over time, this ensures recent data is re-fetched to capture updates.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Facebook Pages and their corresponding fields:
Stream containing general information about your Facebook Page, including profile details, settings, and metadata.
| Field | Type | Description |
| -------------------------------------- | ------- | ------------------------------------------------- |
| `id` | String | The Facebook page ID |
| `page_id` | String | The Facebook page ID (duplicated for consistency) |
| `about` | String | About information of the page |
| `affiliation` | String | The page affiliation |
| `artists_we_like` | String | Artists that the page likes |
| `attire` | String | The attire information for the page |
| `awards` | String | Awards received by the page |
| `band_interests` | String | Band interests of the page |
| `band_members` | String | Band members of the page |
| `bio` | String | Biography of the page |
| `birthday` | String | Birthday of the page |
| `booking_agent` | String | Booking agent information |
| `built` | String | Built date or information |
| `can_checkin` | Boolean | Whether users can check in at this page |
| `can_post` | Boolean | Whether users can post to this page |
| `category` | String | The category of the page |
| `checkins` | Integer | Number of check-ins at the page |
| `company_overview` | String | Company overview information |
| `country_page_likes` | Integer | Number of likes from each country |
| `culinary_team` | String | Culinary team information |
| `current_location` | String | Current location of the page |
| `description` | String | Description of the page |
| `directed_by` | String | Director information |
| `display_subtext` | String | Display subtext of the page |
| `features` | String | Features of the page |
| `followers_count` | Integer | Number of followers |
| `founded` | String | Founded date or information |
| `general_info` | String | General information about the page |
| `general_manager` | String | General manager information |
| `genre` | String | Genre of the page |
| `global_brand_page_name` | String | Global brand page name |
| `global_brand_root_id` | String | Global brand root ID |
| `has_added_app` | Boolean | Whether the page has added an app |
| `has_whatsapp_business_number` | Boolean | Whether the page has a WhatsApp business number |
| `has_whatsapp_number` | Boolean | Whether the page has a WhatsApp number |
| `hometown` | String | Hometown of the page |
| `influences` | String | Influences of the page |
| `is_chain` | Boolean | Whether this is a chain page |
| `is_community_page` | Boolean | Whether this is a community page |
| `is_eligible_for_branded_content` | Boolean | Whether the page is eligible for branded content |
| `is_messenger_bot_get_started_enabled` | Boolean | Whether messenger bot get started is enabled |
| `is_messenger_platform_bot` | Boolean | Whether this is a messenger platform bot |
| `is_owned` | Boolean | Whether the page is owned |
| `is_permanently_closed` | Boolean | Whether the page is permanently closed |
| `is_published` | Boolean | Whether the page is published |
| `is_unclaimed` | Boolean | Whether the page is unclaimed |
| `link` | String | Link to the page |
| `members` | String | Members of the page |
| `merchant_review_status` | String | Merchant review status |
| `mission` | String | Mission of the page |
| `mpg` | String | MPG information |
| `name` | String | Name of the page |
| `network` | String | Network information |
| `personal_info` | String | Personal information |
| `personal_interests` | String | Personal interests |
| `phone` | String | Phone number of the page |
Stream containing published posts from your Facebook Page, including post content, metadata, and engagement indicators.
| Field | Type | Description |
| ----------------------------- | -------- | ------------------------------------------ |
| `id` | String | The post ID |
| `page_id` | String | The Facebook page ID |
| `allowed_advertising_objects` | String | Allowed advertising objects for the post |
| `created_time` | DateTime | The creation time of the post |
| `full_picture` | String | The full picture URL of the post |
| `icon` | String | The icon URL of the post |
| `message` | String | The message text of the post |
| `is_eligible_for_promotion` | Boolean | Whether the post is eligible for promotion |
| `is_expired` | Boolean | Whether the post has expired |
| `is_hidden` | Boolean | Whether the post is hidden |
| `is_instagram_eligible` | Boolean | Whether the post is eligible for Instagram |
| `is_popular` | Boolean | Whether the post is popular |
| `is_published` | Boolean | Whether the post is published |
| `is_spherical` | Boolean | Whether the post contains spherical media |
| `parent_id` | String | The parent post ID if this is a comment |
| `permalink_url` | String | The permanent URL of the post |
| `story` | String | The story text of the post |
| `shares` | Object | Share information |
| `shares.count` | Integer | The number of shares |
| `subscribed` | Boolean | Whether the user is subscribed to the post |
| `status_type` | String | The status type of the post |
| `updated_time` | DateTime | The last update time of the post |
Stream containing lifetime performance metrics for each post, including engagement, reactions, and video view statistics.
> **Note**: This stream provides lifetime metrics for posts. Video-related metrics will only have values for video posts. Additionally, if your page does not support certain metrics, the connector will automatically exclude them to prevent API errors.
| Field | Type | Description |
| ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `page_id` | String | The Facebook page ID |
| `post_id` | String | The post ID |
| `post_created_time` | DateTime | The post creation time |
| `post_clicks` | Integer | Total post clicks |
| `post_reactions_like_total` | Integer | Total like reactions |
| `post_reactions_love_total` | Integer | Total love reactions |
| `post_reactions_wow_total` | Integer | Total wow reactions |
| `post_reactions_haha_total` | Integer | Total haha reactions |
| `post_reactions_sorry_total` | Integer | Total sorry reactions |
| `post_reactions_anger_total` | Integer | Total anger reactions |
| `post_video_views` | Integer | Total video views |
| `post_video_views_unique` | Integer | Unique video views |
| `post_video_views_organic` | Integer | Organic video views |
| `post_video_views_organic_unique` | Integer | Unique organic video views |
| `post_video_views_paid` | Integer | Paid video views |
| `post_video_views_paid_unique` | Integer | Unique paid video views |
| `post_video_views_autoplayed` | Integer | Autoplayed video views |
| `post_video_views_clicked_to_play` | Integer | Clicked-to-play video views |
| `post_video_views_sound_on` | Integer | Video views with sound on |
| `post_video_view_time` | Integer | Total video view time (ms) |
| `post_video_views_15s` | Integer | 15-second video views |
| `post_video_views_60s_excludes_shorter` | Integer | 60-second video views (excludes shorter videos) |
| `post_video_complete_views_organic` | Integer | Organic complete video views |
| `post_video_complete_views_organic_unique` | Integer | Unique organic complete video views |
| `post_video_complete_views_paid` | Integer | Paid complete video views |
| `post_video_complete_views_paid_unique` | Integer | Unique paid complete video views |
| `post_video_avg_time_watched` | Integer | Average time watched (ms) |
| `post_video_length` | Integer | Video length (ms) |
| `post_total_media_view` | Integer | Number of times the post's media was played or displayed |
| `post_total_media_view_unique` | Integer | Number of unique viewers of the post's media; Meta's replacement for the deprecated unique video view metrics |
Stream containing lifetime post media views broken down by `is_from_ads` and `is_from_followers`. It provides a long format structure with one row per post, breakdown dimension, and breakdown value.
| Field | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | String | The Facebook page ID |
| `post_id` | String | The post ID |
| `post_created_time` | DateTime | The post creation time |
| `breakdown_dimension` | String | Which breakdown this row belongs to: 'is\_from\_ads' or 'is\_from\_followers' |
| `breakdown_value` | String | Value of the breakdown dimension as returned by Facebook: for is\_from\_ads, '1' = views from ads (paid) and '0' = organic; for is\_from\_followers, '1' = follower and '0' = non-follower |
| `media_view` | Integer | Number of media views for this post and breakdown value |
Stream containing comments on your Facebook Page posts, including commenter information and engagement metrics.
This stream uses a reduced page size (20 records per API request) to avoid Facebook's "too much data" error when fetching nested comment structures.
| Field | Type | Description |
| ---------------------------- | -------- | ---------------------------------- |
| `id` | String | The comment ID |
| `post_id` | String | The parent post ID |
| `post_created_time` | DateTime | The parent post creation time |
| `page_id` | String | The Facebook page ID |
| `message` | String | The comment message text |
| `created_time` | DateTime | The comment creation time |
| `from` | Object | The user who made the comment |
| `from.id` | String | The commenter's user ID |
| `from.name` | String | The commenter's name |
| `like_count` | Integer | Number of likes on the comment |
| `comment_count` | Integer | Number of replies to the comment |
| `is_hidden` | Boolean | Whether the comment is hidden |
| `attachment` | Object | Attachment on the comment (if any) |
| `attachment.type` | String | The attachment type |
| `attachment.url` | String | The attachment URL |
| `attachment.media` | Object | Media object for the attachment |
| `attachment.media.image` | Object | Image details |
| `attachment.media.image.src` | String | The image source URL |
Stream containing daily page-level performance metrics, including views, engagement, impressions, reactions, and video statistics.
> **Note**: This stream provides daily aggregated metrics for your entire page. Data is fetched in 3-month batches for efficient API usage. If your page does not support certain metrics, the connector will automatically exclude them to prevent API errors.
| Field | Type | Description |
| ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | String | The Facebook page ID |
| `end_time` | DateTime | The end time for the metric period |
| `page_views_total` | Integer | Total page views |
| `page_post_engagements` | Integer | Total post engagements |
| `page_posts_impressions` | Integer | Total post impressions |
| `page_posts_impressions_unique` | Integer | Unique post impressions |
| `page_posts_impressions_paid` | Integer | Paid post impressions |
| `page_posts_impressions_paid_unique` | Integer | Unique paid post impressions |
| `page_posts_impressions_organic` | Integer | Organic post impressions |
| `page_posts_impressions_organic_unique` | Integer | Unique organic post impressions |
| `page_posts_served_impressions_organic_unique` | Integer | Unique organic impressions served |
| `page_posts_impressions_viral` | Integer | Viral post impressions |
| `page_posts_impressions_viral_unique` | Integer | Unique viral post impressions |
| `page_posts_impressions_nonviral` | Integer | Non-viral post impressions |
| `page_posts_impressions_nonviral_unique` | Integer | Unique non-viral post impressions |
| `page_actions_post_reactions_like_total` | Integer | Total like reactions |
| `page_actions_post_reactions_love_total` | Integer | Total love reactions |
| `page_actions_post_reactions_wow_total` | Integer | Total wow reactions |
| `page_actions_post_reactions_haha_total` | Integer | Total haha reactions |
| `page_actions_post_reactions_sorry_total` | Integer | Total sorry reactions |
| `page_actions_post_reactions_anger_total` | Integer | Total anger reactions |
| `page_actions_post_reactions_total` | Object | Total reactions breakdown |
| `page_actions_post_reactions_total.like` | Integer | Total like reactions |
| `page_actions_post_reactions_total.love` | Integer | Total love reactions |
| `page_actions_post_reactions_total.wow` | Integer | Total wow reactions |
| `page_actions_post_reactions_total.haha` | Integer | Total haha reactions |
| `page_actions_post_reactions_total.sorry` | Integer | Total sorry reactions |
| `page_actions_post_reactions_total.anger` | Integer | Total anger reactions |
| `page_total_actions` | Integer | Total page actions |
| `page_video_views` | Integer | Total video views |
| `page_video_views_paid` | Integer | Paid video views |
| `page_video_views_organic` | Integer | Organic video views |
| `page_video_views_autoplayed` | Integer | Autoplayed video views |
| `page_video_views_click_to_play` | Integer | Click-to-play video views |
| `page_video_views_unique` | Integer | Unique video views |
| `page_video_repeat_views` | Integer | Repeat video views |
| `page_video_view_time` | Integer | Total video view time (ms) |
| `page_video_complete_views_30s` | Integer | 30s complete video views |
| `page_video_complete_views_30s_paid` | Integer | Paid 30s complete video views |
| `page_video_complete_views_30s_organic` | Integer | Organic 30s complete video views |
| `page_video_complete_views_30s_autoplayed` | Integer | Autoplayed 30s complete video views |
| `page_video_complete_views_30s_click_to_play` | Integer | Click-to-play 30s complete video views |
| `page_video_complete_views_30s_unique` | Integer | Unique 30s complete video views |
| `page_video_complete_views_30s_repeat_views` | Integer | Repeat 30s complete video views |
| `page_total_media_view` | Integer | Number of times the page's media (videos, posts, stories, ads) was played or displayed |
| `page_total_media_view_unique` | Integer | Number of unique viewers of the page's media; Meta's replacement for the deprecated unique reach and unique video view metrics |
Daily page media views broken down by `is_from_ads` and `is_from_followers`. This stream is Meta's replacement for the deprecated paid/organic reach metrics.
| Field | Type | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | String | The Facebook page ID |
| `end_time` | DateTime | The end time for the metric period |
| `media_view_total` | Integer | Total media views for the period, summed across every breakdown combination |
| `breakdown` | String | Raw is\_from\_ads / is\_from\_followers breakdown of page media views, serialized as a JSON string. Parse downstream to split paid vs organic and follower vs non-follower views. Kept as a string to stay resilient to Meta's still-evolving breakdown response format. |
Lifetime post media views broken down by `is_from_ads` and `is_from_followers`.
| Field | Type | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | String | The Facebook page ID |
| `post_id` | String | The post ID |
| `post_created_time` | DateTime | The post creation time |
| `media_view_total` | Integer | Total media views for the post, summed across every breakdown combination |
| `breakdown` | String | Raw is\_from\_ads / is\_from\_followers breakdown of post media views, serialized as a JSON string. Parse downstream to split paid vs organic and follower vs non-follower views. Kept as a string to stay resilient to Meta's still-evolving breakdown response format. |
Stream containing daily page media views broken down by `is_from_ads` and `is_from_followers`. It provides a long format structure with one row per date, breakdown dimension, and breakdown value.
| Field | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page_id` | String | The Facebook page ID |
| `end_time` | DateTime | The end time of the metric period (one day) |
| `breakdown_dimension` | String | Which breakdown this row belongs to: 'is\_from\_ads' or 'is\_from\_followers' |
| `breakdown_value` | String | Value of the breakdown dimension as returned by Facebook: for is\_from\_ads, '1' = views from ads (paid) and '0' = organic; for is\_from\_followers, '1' = follower and '0' = non-follower |
| `media_view` | Integer | Number of media views for this date and breakdown value |
Stream containing page ratings and recommendations from users.
| Field | Type | Description |
| --------------------- | -------- | ---------------------------------------------- |
| `page_id` | String | The Facebook page ID |
| `created_time` | DateTime | The time the review was created |
| `recommendation_type` | String | The recommendation type (positive or negative) |
| `review_text` | String | The content of the review |
| `reviewer` | Object | The reviewer information |
| `reviewer.id` | String | The Page-scoped ID of the reviewer |
| `reviewer.name` | String | The name of the reviewer |
## API Limitations
Facebook's Graph API has the following limitations that affect the connector:
* **Rate Limits**: The API has standard rate limits. The connector handles pagination automatically and respects these limits.
* **Nested Data Size**: When fetching comments with nested replies, Facebook may return a "too much data" error if the result set is too large. The Post Comments stream uses a reduced page size (20 records per request) to mitigate this issue.
* **Unsupported Metrics**: Facebook may return errors if certain insight metrics are invalid, deprecated, or not supported for a specific page. The connector automatically probes and drops these unsupported metrics to ensure the extraction succeeds for the remaining valid data.
* **Permissions**: The user authorizing the connection must have admin or editor access to the Page to successfully retrieve all data streams.
## Stream to Endpoint Mapping
| Stream | Endpoint | Sync Type | Replication Key |
| -------------------------- | -------------------------------------------- | ----------- | ------------------- |
| Page | `/{page_id}` | Full Table | - |
| Posts | `/{page_id}/published_posts` | Incremental | `created_time` |
| Post Insights | `/{page_id}/published_posts` (with insights) | Incremental | `post_created_time` |
| Post Media Views Breakdown | `/{page_id}/published_posts` (with insights) | Incremental | `post_created_time` |
| Post Comments | `/{page_id}/published_posts` (with comments) | Incremental | `post_created_time` |
| Daily Page Insights | `/{page_id}/insights` | Incremental | `end_time` |
| Page Media Views Breakdown | `/{page_id}/insights` | Incremental | `end_time` |
| Post Media Views Breakdown | `/{page_id}/published_posts` | Incremental | `post_created_time` |
| Reviews | `/{page_id}/ratings` | Full Table | - |
# Data Model
The following diagram illustrates the relationships between the core data streams in Facebook Pages. The arrows indicate the join keys that link the different entities.
```mermaid theme={null}
graph TD;
subgraph "Page Information"
Page("Page")
end
subgraph "Content"
Posts("Posts")
PostComments("Post Comments")
end
subgraph "Performance Data"
PostInsights("Post Insights")
PostMediaViewsBreakdown("Post Media Views Breakdown")
DailyPageInsights("Daily Page Insights")
PageMediaViewsBreakdown("Page Media Views Breakdown")
end
subgraph "Engagement"
Reviews("Reviews")
end
Posts -- "page_id" --> Page
PostComments -- "post_id" --> Posts
PostComments -- "page_id" --> Page
PostInsights -- "post_id" --> Posts
PostInsights -- "page_id" --> Page
PostMediaViewsBreakdown -- "post_id" --> Posts
PostMediaViewsBreakdown -- "page_id" --> Page
DailyPageInsights -- "page_id" --> Page
PageMediaViewsBreakdown -- "page_id" --> Page
Reviews -- "page_id" --> Page
```
# Use Cases for Data Analysis
This guide outlines valuable business intelligence use cases when consolidating Facebook Pages data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).
## Page Performance Analysis
### 1. Daily Page Engagement Overview
Track your page's daily engagement metrics to understand audience interaction patterns.
**Business Value:**
* Monitor daily engagement trends
* Identify high-performing days for content strategy
* Track the balance between organic and paid reach
```sql theme={null}
SELECT
DATE(end_time) AS date,
page_views_total,
page_post_engagements,
page_posts_impressions_organic,
page_posts_impressions_paid,
page_actions_post_reactions_total,
page_video_views
FROM
nekt_raw.facebook_pages_daily_page_insights
WHERE
end_time >= CURRENT_DATE - INTERVAL '30' DAY
ORDER BY
date DESC
```
```sql theme={null}
SELECT
DATE(end_time) AS date,
page_views_total,
page_post_engagements,
page_posts_impressions_organic,
page_posts_impressions_paid,
page_actions_post_reactions_total,
page_video_views
FROM
`nekt_raw.facebook_pages_daily_page_insights`
WHERE
end_time >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY
date DESC
```
| date | page\_views\_total | page\_post\_engagements | page\_posts\_impressions\_organic | page\_posts\_impressions\_paid | page\_actions\_post\_reactions\_total | page\_video\_views |
| ---------- | ------------------ | ----------------------- | --------------------------------- | ------------------------------ | ------------------------------------- | ------------------ |
| 2024-11-27 | 1,234 | 456 | 8,920 | 2,340 | 189 | 567 |
| 2024-11-26 | 1,156 | 398 | 7,845 | 1,890 | 167 | 423 |
| 2024-11-25 | 987 | 312 | 6,230 | 1,560 | 134 | 289 |
### 2. Post Performance Analysis
Analyze individual post performance to understand what content resonates with your audience.
**Business Value:**
* Identify top-performing content
* Understand reaction distribution across posts
* Optimize content strategy based on engagement data
```sql theme={null}
SELECT
p.id AS post_id,
SUBSTRING(p.message, 1, 100) AS post_preview,
p.created_time,
p.shares.count AS share_count,
pi.post_clicks,
pi.post_reactions_like_total,
pi.post_reactions_love_total,
pi.post_reactions_wow_total,
(COALESCE(pi.post_reactions_like_total, 0) +
COALESCE(pi.post_reactions_love_total, 0) +
COALESCE(pi.post_reactions_wow_total, 0) +
COALESCE(pi.post_reactions_haha_total, 0) +
COALESCE(pi.post_reactions_sorry_total, 0) +
COALESCE(pi.post_reactions_anger_total, 0)) AS total_reactions
FROM
nekt_raw.facebook_pages_posts p
LEFT JOIN nekt_raw.facebook_pages_post_insights pi ON p.id = pi.post_id
WHERE
p.created_time >= CURRENT_DATE - INTERVAL '30' DAY
ORDER BY
total_reactions DESC
LIMIT 20
```
```sql theme={null}
SELECT
p.id AS post_id,
SUBSTR(p.message, 1, 100) AS post_preview,
p.created_time,
p.shares.count AS share_count,
pi.post_clicks,
pi.post_reactions_like_total,
pi.post_reactions_love_total,
pi.post_reactions_wow_total,
(COALESCE(pi.post_reactions_like_total, 0) +
COALESCE(pi.post_reactions_love_total, 0) +
COALESCE(pi.post_reactions_wow_total, 0) +
COALESCE(pi.post_reactions_haha_total, 0) +
COALESCE(pi.post_reactions_sorry_total, 0) +
COALESCE(pi.post_reactions_anger_total, 0)) AS total_reactions
FROM
`nekt_raw.facebook_pages_posts` p
LEFT JOIN `nekt_raw.facebook_pages_post_insights` pi ON p.id = pi.post_id
WHERE
p.created_time >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
ORDER BY
total_reactions DESC
LIMIT 20
```
| post\_id | post\_preview | created\_time | share\_count | post\_clicks | post\_reactions\_like\_total | post\_reactions\_love\_total | post\_reactions\_wow\_total | total\_reactions |
| ----------- | --------------------------------------------- | -------------------- | ------------ | ------------ | ---------------------------- | ---------------------------- | --------------------------- | ---------------- |
| 123456\_789 | 🎉 Exciting news! We're launching our new\... | 2024-11-25T14:30:00Z | 45 | 234 | 156 | 89 | 23 | 278 |
| 123456\_790 | Thank you all for your amazing support... | 2024-11-23T10:00:00Z | 32 | 189 | 134 | 67 | 12 | 219 |
### 3. Comment Engagement Analysis
Analyze comment activity to understand audience engagement and sentiment.
**Business Value:**
* Monitor community engagement
* Identify posts that spark conversation
* Track response patterns and community health
```sql theme={null}
WITH comment_stats AS (
SELECT
post_id,
COUNT(*) AS total_comments,
SUM(like_count) AS total_comment_likes,
SUM(comment_count) AS total_replies,
COUNT(CASE WHEN is_hidden = false THEN 1 END) AS visible_comments
FROM
nekt_raw.facebook_pages_post_comments
WHERE
post_created_time >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY
post_id
)
SELECT
p.id AS post_id,
SUBSTRING(p.message, 1, 80) AS post_preview,
p.created_time,
cs.total_comments,
cs.total_comment_likes,
cs.total_replies,
cs.visible_comments
FROM
nekt_raw.facebook_pages_posts p
JOIN comment_stats cs ON p.id = cs.post_id
ORDER BY
cs.total_comments DESC
LIMIT 15
```
```sql theme={null}
WITH comment_stats AS (
SELECT
post_id,
COUNT(*) AS total_comments,
SUM(like_count) AS total_comment_likes,
SUM(comment_count) AS total_replies,
COUNTIF(is_hidden = false) AS visible_comments
FROM
`nekt_raw.facebook_pages_post_comments`
WHERE
post_created_time >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
GROUP BY
post_id
)
SELECT
p.id AS post_id,
SUBSTR(p.message, 1, 80) AS post_preview,
p.created_time,
cs.total_comments,
cs.total_comment_likes,
cs.total_replies,
cs.visible_comments
FROM
`nekt_raw.facebook_pages_posts` p
JOIN comment_stats cs ON p.id = cs.post_id
ORDER BY
cs.total_comments DESC
LIMIT 15
```
| post\_id | post\_preview | created\_time | total\_comments | total\_comment\_likes | total\_replies | visible\_comments |
| ----------- | ------------------------------------------------------------ | -------------------- | --------------- | --------------------- | -------------- | ----------------- |
| 123456\_789 | 🎉 Exciting news! We're launching our new product line... | 2024-11-25T14:30:00Z | 89 | 234 | 45 | 87 |
| 123456\_791 | What's your favorite feature of our service? Let us know\... | 2024-11-24T09:00:00Z | 67 | 156 | 23 | 65 |
### 4. Review Sentiment Analysis
Analyze page reviews to understand customer satisfaction and feedback trends.
**Business Value:**
* Track overall customer satisfaction
* Monitor review volume and sentiment over time
* Identify areas for improvement
```sql theme={null}
SELECT
DATE_TRUNC('week', created_time) AS week,
COUNT(*) AS total_reviews,
COUNT(CASE WHEN recommendation_type = 'positive' THEN 1 END) AS positive_reviews,
COUNT(CASE WHEN recommendation_type = 'negative' THEN 1 END) AS negative_reviews,
ROUND(
COUNT(CASE WHEN recommendation_type = 'positive' THEN 1 END) * 100.0 / COUNT(*),
2
) AS positive_percentage
FROM
nekt_raw.facebook_pages_reviews
WHERE
created_time >= CURRENT_DATE - INTERVAL '90' DAY
GROUP BY
DATE_TRUNC('week', created_time)
ORDER BY
week DESC
```
```sql theme={null}
SELECT
DATE_TRUNC(created_time, WEEK) AS week,
COUNT(*) AS total_reviews,
COUNTIF(recommendation_type = 'positive') AS positive_reviews,
COUNTIF(recommendation_type = 'negative') AS negative_reviews,
ROUND(
COUNTIF(recommendation_type = 'positive') * 100.0 / COUNT(*),
2
) AS positive_percentage
FROM
`nekt_raw.facebook_pages_reviews`
WHERE
created_time >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)
GROUP BY
DATE_TRUNC(created_time, WEEK)
ORDER BY
week DESC
```
| week | total\_reviews | positive\_reviews | negative\_reviews | positive\_percentage |
| ---------- | -------------- | ----------------- | ----------------- | -------------------- |
| 2024-11-25 | 12 | 10 | 2 | 83.33 |
| 2024-11-18 | 8 | 7 | 1 | 87.50 |
| 2024-11-11 | 15 | 12 | 3 | 80.00 |
## Implementation Notes
### Data Quality Considerations
* The **lookback window** is important for post engagement metrics, as reactions and comments can be added to posts days or weeks after publication.
* Daily Page Insights data is fetched in 3-month batches to optimize API usage and avoid rate limits.
* Post Insights metrics provide lifetime values that accumulate over time, while Daily Page Insights provide daily snapshots.
* The `Page Media Views Breakdown` and `Post Media Views Breakdown` streams are Meta's modern replacements for older unique reach and unique video view metrics. You can extract and parse the JSON string field `breakdown` to segment views by ads (paid) vs followers (organic).
* The Reviews stream does not have incremental sync capability, so it performs a full table sync on each extraction.
* **Unsupported metrics**: If specific insights metrics are unsupported or deprecated for your page, they will be automatically dropped from the extraction. The corresponding fields in your table will appear as null.
### API Limits & Performance
* Facebook's Graph API has rate limits. The connector handles pagination automatically and respects these limits.
* The Post Comments stream uses a reduced page size (20 records per request) to avoid Facebook's "too much data" error when fetching nested comment structures.
* For pages with high post volumes, consider selecting only the streams you need to optimize extraction times.
* The `page_id` field is included in all streams to enable easy joins and filtering when you have multiple pages.
## Skills for agents
Facebook Pages connector documentation as plain markdown, for use in AI agent contexts.